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Section 1 
Hardware Description 



1.1 Features • 4-bit HARVARD Architecture 

• High-level Language Oriented CPU 

• 256 x 4 bits of RAM 

• Up to 9 KBytes of ROM 

• 8 Vectored Prioritized Interrupt Levels 

• Low Voltage Operating Range 

• Low Power Consumption 

• Power-down Mode 

• Various On-chip Peripheral Combination Available 

• qFORTH High-level Programming Language 

• Programming and Testing is Supported by an Integrated Software Development System 



1.2 Introduction Atmel's MARC4 microcontroller family is based on a low-power 4-bit CPU core. The 

modular MARC4 architecture is HARVARD like, high-level language oriented and well 
suited to realize high integrated microcontrollers with a variety of applications or cus- 
tomer-specific on-chip peripheral combinations. The MARC4 controller's low voltage 
and low power consumption is perfect for hand-held and battery-operated applications. 

The standard members of the family have selected peripheral combinations for a broad 
range of applications. 

Programming is supported by an easy-to-use PC based software development system 
with a high-level language qFORTH compiler and a real-time emulator. The stack-ori- 
ented microcontroller concept enables the qFORTH compiler to generate a compact 
and efficient MARC4 program code. 
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1 .3 General 

Description 



The MARC4 microcontroller consists of an advanced stack-based 4-bit CPU core and 
application-specific, on-chip peripherals such as I/O ports, timers, counters, ADC, etc. 

The CPU is based on the HARVARD architecture with a physically separate program 
memory (ROM) and data memory (RAM). Three independent buses, the instruction-, 
the memory- and the I/O bus, are used for parallel communication between ROM, RAM 
and peripherals. This enhances program execution speed by allowing both instruction 
prefetching, and a simultaneous communication to the on-chip peripheral circuitry. 

The powerful integrated interrupt controller, with eight prioritized interrupt levels, sup- 
ports fast processing of hardware events. 

The MARC4 is designed for the qFORTH high-level programming language. A lot of 
qFORTH instructions and two stacks, the Return Stack and the Expression Stack, are 
already implemented. The architecture allows high-level language programming without 
any loss of efficiency and code density. 



Figure 1-1. MARC4 Core 
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1.4 Components of 
MARC4 Core 

1.4.1 Program Memory 
(ROM) 



1 .4.2 Data Memory (RAM) 



1.4.2.1 Expression Stack 



The core contains the program memory (ROM), data memory (RAM), ALU, Program 
Counter, RAM Address Register, instruction decoder and interrupt controller. The fol- 
lowing sections describe each of these parts. 

The MARC4's program memory contains the customer-application program. The 12-bit 
wide Program Counter can address up to 4 Kbytes of program memory. The access of 
program memory with more than 4 K is possible using the bank-switching method. One 
of 4 memory banks can be selected with bit 2 and 3 of the ROM bank register (RBR). 
Each ROM bank has a size of 2 Kbytes and is placed above the base bank in the upper 
2 K (800h-FFFh) of the address space. This therefore enables program memory sizes of 
up to 10 Kbytes. 1 Kbyte of bank 3 is normally reserved for test software purposes. After 
any hardware reset, ROM Bank 1 is selected automatically. 

The program memory starts with a 512 byte segment (Zero Page) which contains pre- 
defined start addresses for interrupt service routines and special subroutines accessible 
with single byte instructions (SCALL). The corresponding memory map is shown in Fig- 
ure 1-2. 

Look-up tables of constants are also stored in ROM and are accessed via the MARC4 
built in TABLE instruction. 

The MARC4 contains a 256 x 4-bit wide static Random Access Memory (RAM). It is 
used for the Expression Stack, the Return Stack and as data memory for variables and 
arrays. The RAM is addressed by any of the four 8-bit wide RAM Address Registers SP, 
RP, XandY. 

The 4-bit wide Expression Stack is addressed with the Expression Stack Pointer (SP). 
All arithmetic, I/O and memory reference operations take their operands from, and 
return their result to the Expression Stack. The MARC4 performs the operations with the 
top of stack items (TOS and TOS-1). The TOS register contains the top element of the 
Expression Stack and works in the same way as an accumulator. 

This stack is also used for passing parameters between subroutines, and as a scratch- 
pad area for temporary storage of data. 



Figure 1-2. ROM Map 
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Figure 1-3. RAM Map 
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1.4.2.2 Return Stack 



1.4.3 Registers 

1.4.3.1 Program Counter 
(PC) 



1.4.3.2 RAM Address 
Register 



The 12-bit wide Return Stack is addressed by the Return Stack Pointer (RP). It is used 
for storing return addresses of subroutines, interrupt routines and for keeping loop-index 
counters. The return stack can also be used as a temporary storage area. The MARC4 
Return Stack starts with the AUTOSLEEP vector at the RAM location FCh and 
increases in the address direction OOh, 04h, 08h, ... to the top. 

The MARC4 instruction set supports the exchange of data between the top elements of 
the expression and the Return Stack. The two stacks within the RAM have a user-defin- 
able maximum depth. 

The MARC4 controller has six programmable registers and one condition code register. 
They are shown in the programming model in Figure 1-4. 

The Program counter (PC) is a 12-bit register that contains the address of the next 
instruction to be fetched from the ROM. Instructions currently being executed are 
decoded in the instruction decoder to determine the internal micro-operations. 

For linear code (no calls or branches), the program counter is incremented with every 
instruction cycle. If a branch, call, return instruction or an interrupt is executed, the pro- 
gram counter is loaded with a new address. 

The program counter is also used with the table instruction to fetch 8-bit wide ROM 
constants. 

The RAM is addressed with the four 8-bit wide RAM address registers SP, RP, X and Y. 
These registers allow the access to any of the 256 RAM nibbles. 
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Figure 1-4. Programming Model 
11 
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1 .4.3.3 Expression Stack 
Pointer (SP) 



1.4.3.4 Return Stack Pointer 
(RP) 



The Stack Pointer (SP) contains the address of the next-to-top 4-bit item (TOS-1) of the 
Expression Stack. The pointer is automatically pre-incremented if a nibble is pushed 
onto the stack, or post-decremented if a nibble is removed from the stack. Every post- 
decrement operation moves the item (TOS-1) to the TOS register before the SP is 
decremented. 

After a reset, the stack pointer has to be initialized with the compiler variable SO 
(" >SP SO") to allocate the start address of the Expression Stack area. 

The Return Stack Pointer points to the top element of the 12-bit wide Return Stack. The 
pointer automatically pre-increments if an element is moved onto the stack, or it post- 
decrements if an element is removed from the stack. The Return Stack Pointer incre- 
ments and decrements in steps of 4. This means that every time a 12-bit element is 
stacked, a 4-bit RAM location is left unwritten. This location is used by the qFORTH 
compiler to allocate 4-bit variables. 
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1.4.3.5 RAM Address 

Register (X and Y) 



1.4.3.6 Top of Stack (TOS) 



1.4.3.7 Condition Code 
Register (CCR) 



1 .4.3.8 Carry/Borrow (C) 



1.4.3.9 Branch (B) 



1.4.3.10 Interrupt Enable (I) 



1.4.4 ALU 



To support the AUTOSLEEP feature, read and write operations to the RAM address 
FCh using the Return Stack Pointer are handled in a special way. Read operations will 
return the AUTOSLEEP address OOOh, whereby write operations have no effect. After a 
reset, the Return Stack Pointer has to be initialized with " >RP FCh ". 

The X and Y registers are used to address any 4-bit element in the RAM. A fetch opera- 
tion moves the addressed nibble onto the TOS. A store operation moves the TOS to the 
addressed RAM location. 

By using either the pre-increment or post-decrement addressing mode, it is convenient 
to compare, fill or move arrays in the RAM. 

The Top of Stack Register is the accumulator of the MARC4. All arithmetic/logic, mem- 
ory reference and I/O operations use this register. The TOS register gets the data from 
the ALU, the ROM, the RAM or via the I/O bus. 

The 4-bit wide Condition Code Register contains the branch, the carry and the interrupt 
enable flag. These bits indicate the current state of the CPU. The CCR flags are set or 
reset by ALU operations. The instructions SET_BCF, TOG_BF, CCR! and Dl allow a 
direct manipulation of the Condition Code Register. 

The Carry/Borrow flag indicates that the borrowing or carrying out of the Arithmetic 
Logic Unit (ALU) occurred during the last arithmetic operation. During shift and rotate 
operations, this bit is used as a fifth bit. Boolean operations have no effect on the Carry 
flag. 

The Branch flag controls the conditional program branching. When the Branch flag has 
been set by one of the previous instructions, a conditional branch is taken. This flag is 
affected by arithmetic, logic, shift, and rotate operations. 

The Interrupt Enable flag enables or disables the interrupt processing on a global basis. 
After a reset or by executing the Dl instruction, the Interrupt Enable flag is cleared and 
all interrupts are disabled. The microcontroller does not process further interrupt 
requests until the Interrupt Enable flag is set again by executing either an El, RTI or 
SLEEP instruction. 

The 4-bit ALU performs all the arithmetic, logical, shift and rotate operations with the top 
two elements of the Expression Stack (TOS and TOS-1) and returns their result to the 
TOS. The ALU operations affect the Carry/Borrow and Branch flag in the Condition 
Code Register (CCR). 

Figure 1-5. ALU Zero Address Operations 
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1.4.5 Instruction Set 



The MARC4 instruction set is optimized for the qFORTH high-level programming lan- 
guage. A lot of MARC4 instructions are qFORTH words. This enables the compiler to 
generate a fast and compact program code. 
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The MARC4 is a zero address machine with a compact and efficient instruction set. The 
instructions contain only the operation to be performed but no source or destination 
address information. The operations are performed with the data placed on the stack. 

An instruction pipeline enables the controller to fetch the next instruction from ROM at 
the same time as the present instruction is being executed. One- and two-byte instruc- 
tions are executed within 1 to 4 machine-cycles. Most of the instructions have a length 
of one byte and are executed in only one machine cycle. 

A complete overview of the MARC4 instruction set includes the TABLE instruction set. 

1.4.5.1 MARC4 Instruction The internal instruction timing and pipelining during the MARC4's instruction execution 
Timing are shown in Figure 1-6. 

The figure shows the timing for a sequence of three instructions. A machine cycle con- 
sists of two system-clock cycles. The first and second instruction needs one 
machine-cycle and the third instruction needs two machine-cycles. 

1.4.6 I/O Bus Communication between the core and the on-chip peripherals takes place via the I/O 

bus. This bus is used for read and write accesses, for interrupt requests, for peripheral 
reset and for the SLEEP mode. The operation mode of the 4-bit wide I/O bus is deter- 
mined by the control signals N_Write, N_Read, N_Cycle and N_Hold (see Table 1-1 on 
page 8). 

During IN/OUT operations, the address and data, and during an interrupt cycle the low 
and the high priority interrupts are multiplexed by using the N_Cycle signal. When 
N_Cycle is low the address respectively or the low interrupts "0, 1 , 2, 3" are sent, when 
N_Cycle is high the data respectively or the higher priority interrupts "4, 5, 6, 7" are 
transfered (see Figure 1-7). 

An IN operation transfers the port address from TOS (Top Of Stack) onto the I/O bus 
and reads the data back on TOS. An OUT operation transfers both the port address 
from TOS and the data from TOS-1 onto the I/O bus. 

Note that the interrupt controller samples interrupt requests during the non-l/O cycles. 
Therefore, IN and OUT instructions may cause an interrupt delay. To minimize interrupt 
latency, avoid immediate consecutive IN and OUT instructions. 

Figure 1-6. Instruction Cycle (Pipelining) 
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Table 1-1. I/O Bus Modes 



Mode 


N_Read 
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Figure 1-7. Timing for IN/OUT Operations and Interrupt Requests 
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1.4.7 Interrupt Structure 



1.4.7.1 Interrupt Processing 



The I/O bus is internal and therefore not accessible to the customer on the final 
microcontroller. 

The MARC4 can handle interrupts with eight different priority levels. They can be gener- 
ated from internal or external hardware interrupt sources or by a software interrupt from 
the CPU itself. Each interrupt level has a hard-wired priority and an associated vector for 
the service routine in the ROM (see Table 1-2). The programmer can enable or disable 
all interrupts at once by setting or resetting the Interrupt-enable flag (I) in the CCR. 

To process the eight different interrupt levels, the MARC4 contains an interrupt control- 
ler with the 8-bit wide Interrupt Pending and Interrupt Active Register. The interrupt 
controller samples all interrupt requests on the I/O bus during every non-l/O instruction 
cycle and latches them in the Interrupt Pending Register. If no higher priority interrupt is 
present in the Interrupt Active Register, it signals the CPU to interrupt the current pro- 
gram execution. If the interrupt enable bit is set, the processor enters an interrupt 
acknowledge cycle. During this cycle, a SHORT CALL instruction to the service routine 
is executed and the 12-bit wide current PC is saved on the Return Stack automatically. 
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Figure 1-8. Interrupt Handling 
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1.4.7.2 Interrupt Latency 



1 .4.7.3 Software Interrupts 



1.4.7.4 Hardware Interrupts 



An interrupt service routine is finished with the RTI instruction. This instruction resets the 
corresponding bits in the Interrupt Pending/Active Register and moves the return 
address from the Return Stack to the Program Counter. 

When the Interrupt Enable flag has been reset (interrupts are disabled), the execution of 
interrupts is inhibited, but not the logging of the interrupt requests in the Interrupt Pend- 
ing Register. The execution of the interrupt will be delayed until the Interrupt Enable flag 
is set again. But note that interrupts are lost if an interrupt request occurs during the cor- 
responding bit in the Pending Register is still set. 

After any hardware reset (power-on, external or watchdog reset), the Interrupt Enable 
flag, the Interrupt Pending and Interrupt Active Registers are reset. 

The interrupt latency is the time from the occurrence of the interrupt event to the inter- 
rupt service routine being activated. In the MARC4 this takes between three to five 
machine cycles depending on the state of the core. 

The programmer can generate interrupts using the software interrupt instruction (SWI) 
which is supported in qFORTH by predefined macros named SWI0...SWI7. The soft- 
ware-triggered interrupt operates exactly in the same way as any hardware-triggered 
interrupt. The SWI instruction takes the top two elements from the Expression Stack and 
writes the corresponding bits via the I/O bus to the Interrupt Pending Register. There- 
fore, by using the SWI instruction, interrupts can be re-prioritized or lower priority 
processes scheduled for later execution. 

Hardware interrupt sources such as external interrupt inputs, timers etc. are used for 
fast automatically event-controlled program flow. The different vectored interrupts permit 
program dividing into different interrupt-controlled tasks. 
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Figure 1-9. Interrupt Request Cycle 
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Table 1-2. Interrupt Priority Table 
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Figure 1-10. Timing Sleep Mode 
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1.5 Reset The reset puts the CPU into a well-defined condition. The reset can be triggered by 

switching on the supply voltage, by a break-down of the supply voltage, by the watchdog 
timer or by pulling the NRST pad to low. 

After any reset, the Interrupt Enable flag in the Condition Code Register (CCR), the 
Interrupt Pending Register and the Interrupt Active Register are reset. During the reset 
cycle, the I/O bus control signals are set to "reset mode", thereby initializing all on-chip 
peripherals. 

The reset cycle is finished with a short call instruction (opcode C1h) to the ROM- 
address 008h. This activates the initialization routine $RESET. In this routine the stack 
pointers, variables in the RAM and the peripheral must be initialized. 



1 .6 Sleep Mode The sleep mode is a shutdown condition which is used to reduce the average system 

power consumption in applications where the microcontroller is not fully utilized. In this 
mode, the system clock is stopped. The sleep mode is entered with the SLEEP instruc- 
tion. This instruction sets the Interrupt Enable bit (I) in the Condition Code Register to 
enable all interrupts and stops the core. During the sleep mode, the peripheral modules 
remain active and are able to generate interrupts. The microcontroller exits the SLEEP 
mode with any interrupt or a reset. 

The sleep mode can only be kept when none of the Interrupt Pending or Active Register 
bits are set. The application of the $AUTOSLEEP routine ensures the correct function of 
the sleep mode. 

The total power consumption is directly proportional to the active time of the microcon- 
troller. For a rough estimation of the expected average system current consumption, the 
following formula should be used: 

'total = 'sleep + CdD x "'"active^'total) 

l DD depends on V DD and f SY scL- 



1.7 Peripheral All communication to and from on-chip peripheral modules takes place via the periph- 

Communication eral I/O bus. In this way the I/O does not interfere with core internal operations. Data 
transfer is always mastered by the core CPU. A peripheral device, if necessary, can 
however draw attention to itself by means of an interrupt. 

1.7.1 Port Communication The MARC4 peripheral modules are l/O-mapped by using an IN or OUT instruction 

which in turn either inputs or outputs a 4-bit data or from one of 16 direct accessible port 
addresses. 

Before an OUT instruction is executed the port destination address and the data to be 
transmitted must be pushed onto the Expression Stack. 
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Example: 



: TurnLED_Off 
8 Port4 OUT 



Figure 1-11. OUT Instruction - Stack Effects 



TOS 



Data 



TOS 



Addr 



Data 



TOS 



In the case of an IN instruction only the port address needs to be pushed onto the 
Expression Stack. 

Example: 

: KeyPressed? 

Keyln IN 



Figure 1-12. IN Instruction - Stack Effects 



TOS 



Addr 



TOS — i 



Data 



For more complex peripherals please refer to the corresponding data sheets and the 
supplied hardware programming routines. 



1.8 Emulation The basic function of emulation is to test and evaluate the customer's program and 

hardware in real time. This therefore enables the analysis of any timing, hardware or 
software problem. For emulation purposes, all MARC4 controllers include a special 
emulation mode. In this mode, the internal CPU core is inactive and the I/O buses are 
available via Port 0 and Port 1 to allow an external access to the on-chip peripherals. 
The MARC4 emulator uses this mode to control the peripherals of any MARC4 control- 
ler (target chip) and emulates the lost ports for the application. 

A special evaluation chip (EVC) with a MARC4 core, additional breakpoint logic and pro- 
gram memory interface takes over the core function and executes the program from an 
external RAM on the emulator board. 
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Figure 1-13. MARC4 Emulation 



The MARC4 emulator can stop and restart a program at specified points during execu- 
tion, making it possible for the applications engineer to view the memory contents and 
those of various registers during program execution. The designer also gains the ability 
to analyze the executed instruction sequences and all the I/O activities. 



Trace 
memory 



Control 
logic 



MARC4 Emulator 



Program / 
memory 



MARC4 
emulation-CPU 



CORE 



Emulator Target Board 



I/O bus 



PortO 



Port 1 



I/O control 



Emulation control 



SYSCL/ 
TCL, 
TE, NRST 



MARC4 Target Chip 



CORE 
(inactive) 



Peripherals 





Personal Computer 



Application-specific Hardware 
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Section 2 
Instruction Set 



2.1 Introduction Most of the MARC4 instructions are single-byte instructions. The MARC4 is a zero 

address machine where the instruction to be performed contains only the operation and 
not the source or destination addresses of the data. Altogether, there are five types of 
instruction formats for the MARC4 processor. 

A Literal is a 4-bit constant value which is placed on the data stack. In the MARC4 native 
code they are represented as LIT_<value>, where <value> is the hexadecimal repre- 
sentation from 0 to 15 (0..F). This range is a result of the MARC4's 4-bit data width. 

The long RAM address format is used by the four 8-bit RAM address registers which 
can be pre-incremented, post-decremented or loaded directly from the MARC4's inter- 
nal bus. This results in a directly accessible RAM address space of up to 256 x 4 bits. 

The 6-bit short address and the 12-bit long address formats are both used to address 
the byte-wide ROM via call and conditional branch instructions. This results in a ROM 
address space of up to 4 K x 8-bit words. 

The MARC4 instruction set includes both short and long call instructions as well as con- 
ditional branch instructions. The short instructions are single-byte instructions with the 
jump address included in the instruction. On execution, the lower 6 bits from the instruc- 
tion word are directly loaded into the PC. 

Short call (SCALL) and short branch (SBRA) instructions are handled in different ways. 
SCALL jumps to one of 64 evenly distributed addresses within the zero page (from 000 
to 1 FF hex). The short branch instruction allows a jump to one of 64 addresses con- 
tained within the current page. Long jump instructions can jump anywhere within the 
ROM area. The CALL and SCALL instructions write the incremented Program Counter 
contents to the Return Stack. This address is loaded back to the PC when the associ- 
ated EXIT or RTI instruction is encountered. 
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Figure 2-1. MARC4 Opcode Formats 



1) Zero address operation 
(ADD, SUB, etc..) 

2) Literal 
(4-bit data) 



3) Short ROM address 
(6-bit address, 2 cycles) 



4) Long ROM address 
(12-bit address, 2 cycles) 



5) Long RAM address 
(8-bit address, 2 cycles) 
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Table 2-1. Instruction Set Overview 



00 


ADD 


10 


SHL 


20 


TABLE 


30 


[X]@ 


01 


ADDC 


11 


ROL 


21 




31 


[+X]@ 


02 


SUB 


12 


SHR 


22 


>R 


32 


[X-]@ 


03 


SUBB 


13 


ROR 


23 


I R@ 


33 


[>X]@ $xx 


04 


XOR 


14 


INC 


24 




34 


[Y]@ 


05 


AND 


15 


DEC 


25 


EXIT 


35 


[+Y]@ 


06 


CMP_EQ 


16 


DAA 


26 


SWAP 


36 


[Y-]@ 


07 


CMP_NE 


17 


NOT 


27 


OVER 


37 


[>Y]@ $xx 


08 


CMP_LT 


18 


TOG_BF 


28 


2>R 


38 


[X]! 


09 


CMP_LE 


19 


SET_BCF 


29 


3>R 


39 


[+X]I 


OA 


CMP_GT 


1A 


Dl 


2A 


2R@ 


3A 


[X-]! 


OB 


CMP_GE 


1B 


IN 


2B 


3R@ 


3B 


[>X]! $xx 


OC 


OR 


1C 


DECR 


2C 


ROT 


3C 


[Y]l 


OD 


CCR@ 


1D 


RTI 


2D 


DUP 


3D 


[+Y]! 


OE 


CCR! 


1E 


SWI 


2E 


DROP 


3E 


[Y-]l 


OF 


SLEEP 


1F 


OUT 


2F 


DROPR 


3F 


[>Y]! $xx 




40 


CALL $0xx 


50 


BRA $0xx 


60 


LIT_0 


70 


SP@ 


41 


CALL $1 xx 


51 


BRA $1 xx 


61 


LIT_1 


71 


RP@ 


42 


CALL $2xx 


52 


BRA $2xx 


62 


LIT_2 


72 


X@ 


43 


CALL $3xx 


53 


BRA $3xx 


63 


LIT_3 


73 


Y@ 


44 


CALL $4xx 


54 


BRA $4xx 


64 


LIT_4 


74 


SP! 


45 


CALL $5xx 


55 


BRA $5xx 


65 


LIT_5 


75 


RP! 


46 


CALL $6xx 


56 


BRA $6xx 


66 


LIT_6 


76 


X! 


47 


CALL $7xx 


57 


BRA $7xx 


67 


LIT_7 


77 


Y! 


48 


CALL $8xx 


58 


BRA $8xx 


68 


LIT_8 


78 


>SP $xx 


49 


CALL $9xx 


59 


BRA $9xx 


69 


LIT_9 


79 


>RP $xx 


4A 


CALL $Axx 


5A 


BRA $Axx 


6A 


LIT_A 


7A 


>X $xx 


4B 


CALL $Bxx 


5B 


BRA $Bxx 


6B 


LIT_B 


7B 


>Y $xx 


4C 


CALL $Cxx 


5C 


BRA $Cxx 


6C 


LIT_C 


7C 


NOP 


4D 


CALL $Dxx 


5D 


BRA $Dxx 


6D 


LIT_D 


7D 




4E 


CALL $Exx 


5E 


BRA $Exx 


6E 


LIT_E 


7E 




4F 


CALL $Fxx 


5F 


BRA $Fxx 


6F 


LIT_F 


7F 






80..BF 


SBRA $xxx 


Short branch inside current page 


C0..FF 


SCALL $xxx 


Short subroutine CALL into "zero page" 



MARC4 4-bit Microcontrollers Programmer's Guide 



2-3 



4747A-4BMCU-01/04 



Instruction Set 



2.1.1 



Descripion of 
Identifiers and 
Abbreviations Used 



2.1.2 



Stack Notation 



n1 n2 n3 


Three nibbles on the Expression Stack 


n3n2n1 


Three nibbles on the Return Stack which combine to form a 12-bit word 


un2n1 


Two nibbles on the Return Stack (i.e. DO loop index and limit), "u" is an 
unused (undefined) nibble on the Return Stack 


In 


1's complement of the 4-bit word n 


3210 


Numbered bits within a 4-bit word 


Sxx 


8-bit hexadecimal RAM address 


Sxxx 


2-bit hexadecimal ROM address 


PC 


Program Counter (12 bits) 


SP 


Expression Stack Pointer (8 bits), the RAM Address Register which 
points to the RAM location containing the second nibble (TOS-1) on 
the Expression Stack 


RP 


Return Stack Pointer (8 bits), the RAM Address Register which points 
to the last entry on the return address stack 


X 


RAM Address Register (8 bits) 


Y 


RAM Address Register Y (8 bits), these registers can be used in 3 dif- 
ferent addressing modes 

(direct, pre-incremented or post-decremented addressing) 


TOS 


Top of (Expression) Stack (4 bits) 


CCR 


Condition Code Register (4 bits) which contains: 


I [bit 0] 


Interrupt-enable flag 


B [bit 1] 


Branch flag 


% [bit 2] 


Reserved (currently unused) 


C [bit 3] 


Carry flag 


/C 


NOT Carry (Borrow) flag 



E ( n1 n2 — n ) 


Expression Stack contents (rightmost 4-bit digit is in TOS) 


R ( n1n2n3 — ) 


Return Stack contents (rightmost 12-bit word is top entry) 


RET ( — ROMAddr ) 


Return Address Stack effects 


EXP(-) 


Expression/Data Stack effects 


True condition 


= Branch flag set in CCR 


False condition 


= Branch flag reset in CCR 


n 


4-bit data value (nibble) 


d 


8-bit data value (byte) 


addr 


8-bit RAM address 


ROMAddr 


12-bit ROM address 
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Table 2-2. Instruction Set 



Code 
[hex] 


Mnemonic 


Operation 


Symbolic Description [Stack Effects] 


Instr. 
Cycles 


Flags 
C % B I 


00 


ADD 


Add the top 2 stack digits 


E(n1 n2-n1+n2) 
If overflow 
then B:=C:=1 
else B:=C:=0 


1 


XXX- 


01 


ADDC 


Add with carry the top 2 stack 
digits 


E(n1 n2-n1+n2+C) 
If overflow 
then B:=C:=1 
else B:=C:=0 


1 


XXX- 


02 


SUB 


2's complement subtraction of 
the top 2 digits 


E(n1 n2-n1+/n2+1 ) 
If overflow 
then B:=C:=1 
else B:=C:=0 


1 


XXX- 


03 


SUBB 


1 's complement subtraction of 
the top 2 digits 


E ( n1 n2 -- n1+/n2+/C ) 
If overflow 
then B:=C:=1 

CIOC LJ. — — \J 


1 


XXX- 


04 


XOR 


Exclusive-OR top 2 stack digits 


E(n1 n2-n1 XOR n2 ) 
If result=0 then B:=1 

plop R--f) 

CIOC LJ. — \J 


1 


■XX- 


05 


AND 


Bitwise-AND top 2 stack digits 


E(n1 n2-n1 AND n2 ) 
If result=0 then B:=1 

plop R-f) 


1 


■XX- 


06 


CMP_EQ 


Equality test for top 2 stack 
digits 


E(n1 n2--n1 ) 
If n1=n2 then B:=1 

plop R--f) 

CI JC LJ . — \J 


1 


XXX- 


07 


CMPJME 


Inequality test for top 2 stack 
digits 


E(n1 n2--n1 ) 
If n1on2 then B:=1 

plop R -f) 

CI3C LJ . — \J 


1 


XXX- 


08 


CMP_LT 


Less-than test for top 2 stack 
digits 


E(n1 n2-n1 ) 
If n1<n2 then B:=1 

plop R— f) 

Clod LJ. — \J 


1 


XXX- 


09 


CMP_LE 


Less-or-equal for top 2 stack 
digits 


E(n1 n2--n1 ) 

If n1«=n2 then B:=1 

plop R— f) 

CISC LJ. — \J 


1 


XXX- 


OA 


CMP_GT 


Greater-than for top 2 stack 
digits 


E(n1 n2--n1 ) 
If n1>n2 then B:=1 

plop R -f) 

CIOC LJ. — vJ 


1 


XXX- 


OB 


CMP_GE 


Greater-or-equal for top 2 stack 
digits 


F 1 n1 n? — n1 ) 

1_ 1 1 1 1 1 is— III I 

If n1>=n2 then B:=1 
else B:=0 


1 


XXX- 


OC 


OR 


Bitwise-OR top 2 stack digits 


E(n1 n2--n1 OR n2 ) 
If result=0 then B:=1 
else B:=0 


1 


■XX- 


OD 


CCR@ 


Copy condition code onto TOS 


E ( - n ) R ( - ) 


1 




OE 


CCR! 


Restore condition codes 


E ( n - ) R ( - ) 


1 


X X X X 


OF 


SLEEP 


CPU in "sleep mode", 
interrupts enabled 


E ( - ) R ( - ) 
l:=1 


1 


-X- 1 
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Table 2-2. Instruction Set (Continued) 



Code 
[hex] 


Mnemonic 


Operation 


Symbolic Description [Stack Effects] 


Instr. 
Cycles 


Flags 
C % B I 


10 


SHL 


Shift TOS left into carry 


C<-197>3210<-0 
B:=C:=MSB 


1 


XXX- 


11 


ROL 


Rotate TOS left through carry 


..<--C<~321 0<-C<-.. 
B:=C:=MSB 


1 


XXX- 


12 


SHR 


Shift TOS right into carry 


0->3210->C 
B:=C:=LSB 


1 


XXX- 


13 


ROR 


Rotate TOS right through carry 


..~>C~>3210->C~>.. 
B:=C:=LSB 


1 


XXX- 


14 


INC 


Increment TOS 


E ( n - n+1 ) 

If result=0 then B:=1 

else B:=0 


1 


■XX- 


15 


DEC 


Decrement TOS 


E ( n - n-1 ) 

If result=0 then B:=1 

else B:=0 


1 


■XX- 


16 


DAA 


Decimal adjust for addition 
(in BCD arithmetic) 


If TOS>9 OR C=1 
then E ( n - n+6 ) 
B:=C:=1 

else E ( n -- n) R (-) 
B:=C:=0 


1 


1x1- 
0x0- 


17 


NOT 


1 's complement of TOS 


E ( n - In ) 

If result=0 then B:=1 

else B:=0 


1 


■XX- 


18 


TOG_BF 


Toggle Branch flag 


If B = 1 then B:=0 
else B:=1 


1 


■XX- 


19 


SET_BCF 


Set Branch and Carry flag 


B:=C:=1 


1 


1x1- 


1A 


Dl 


Disable all interrupts 


E ( - ) R ( - ) 
l:=0 


1 


-x-0 


1B 


IN 


Read data from 4-bit I/O port 


E ( port - n ) 

If port=0 then B:=1 

else B:=0 


1 


■XX- 


1C 


DECR 


Decrement index on Return 
Stack 


R ( uun -- uun-1 ) 
If n-1=0 then B:=0 
else B:=1 


2 


-10- 
-01 - 


1D 


RTI 


Return from interrupt routine; 
enable all interrupts 


E ( - ) R ( $xxx - ) 
PC := $xxx 


2 





1E 


SWI 


Software interrupt 


E ( n1 n2 - ) R ( - ) 
[n1,n2 = 0,1,2,4,8] 


1 


- X - - 


1F 


OUT 


Write data to 4-bit I/O port 


E ( n port - ) R ( -- ) 


1 


- X - - 


20 
21 


TABLE 


Fetch an 8-bit ROM constant 
and performs an EXIT to 
Ret_PC 


E ( -- nh nl ) 

R ( Ret_PC ROM_addr - ) 
PC:= Ret_PC 


3 




22 


>R 


Move (loop) index onto Return 
Stack 


E ( n - ) 
R ( - uun) 


1 




23 


I 

R@ 


Copy (loop) index from the 
Return Stack onto TOS 


E ( - n ) 

R ( uun -- uun) 


1 




24 
25 


EXIT 


Return from subroutine (" ; ") 


E ( - ) R ( $xxx -) 
PC:=$xxx 


2 
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Table 2-2. Instruction Set (Continued) 



Code 
[hex] 


Mnemonic 


Operation 


Symbolic Description [Stack Effects] 


Instr. 
Cycles 


Flags 
C % B I 


26 


SWAP 


Exchange the top 2 digits 


E ( n1 n2 -- n2 n1 ) 
R ( - ) 


1 




27 


OVER 


Push a copy of TOS-1 onto 
TOS 


E ( n1 n2 - n1 n2 n1 ) 
R ( - ) 


1 




28 


2>R 


Move top 2 digits onto Return 
Stack 


E ( n1 n2 -- ) 
R ( -- un1n2 ) 


3 




29 


3>R 


Move top 3 digits onto Return 
Stack 


E ( n1 n2 n3 -- ) 
R ( - n1n2n3 ) 


4 




2A 


2R@ 


Copy 2 digits from Return to 
Expression Stack 


E ( - n1 n2 ) 

R ( un1n2 -- un1n2 ) 


2 




2B 


3R@ 


Copy 3 digits from Return to 
Expression Stack 


E ( - n1 n2 n3 ) 

R ( n1n2n3 -- n1n2n3 ) 


4 




2C 


ROT 


Move third digit onto TOS 


E ( n1 n2 n3 - n2 n3 n1 ) 
R (-- ) 


3 




2D 


DUP 


Duplicate the TOS digit 


E ( n - n n ) 
R(-) 


1 





2E 


DROP 


Remove TOS digit from the 
Expression Stack 


E ( n - ) 

R(-) 

SP:=SP-1 


1 





2F 


DROPR 


Remove one entry from the 
Return Stack 


E(-) 
R( uuu -- ) 
RP:=RP-4 


1 





30 


[X]@ 


Indirect fetch from RAM 
addressed by the X register 


E ( - n ) 
R(-) 
X:=X Y:=Y 


1 





31 


[+X]@ 


Indirect fetch from RAM 
addressed by the 
pre-incremented X register 


E ( - n ) 
R(-) 

X:=X+1 Y:=Y 


1 





32 


[X-]@ 


Indirect fetch from RAM 
addressed by the 
post-decremented X register 


E ( - n ) 
R(-) 
X:=X-1 Y:=Y 


1 





33 xx 


[>X]@ $xx 


Direct fetch from RAM 
addressed by the X register 


E ( - n ) 
R(-) 
X:=$xx Y:=Y 


2 





34 


[Y]@ 


Indirect fetch from RAM 
addressed by the Y register 


E ( - n ) 
R(-) 
X:=X Y:=Y 


1 





35 


[+Y]@ 


Indirect fetch from RAM 
addressed by the 
pre-incremented Y register 


E ( - n ) 
R(-) 

X:=X Y:=Y+1 


1 





36 


[Y-]@ 


Indirect fetch from RAM 
addressed by the 
post-decremented Y register 


E ( - n ) 
R(-) 
X:=X Y:=Y-1 


1 





37 xx 


[>Y]@ $xx 


Direct fetch from RAM 
addressed by the Y register 


E ( - n ) 
R(-) 
X:=X Y:=$xx 


2 




38 


[X]! 


Indirect store into RAM 
addressed by the X register 


E ( n - ) R ( — ) X:=X Y:=Y 


1 
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Table 2-2. Instruction Set (Continued) 



Code 
[hex] 


Mnemonic 


Operation 


Symbolic Description [Stack Effects] 


Instr. 
Cycles 


Flags 
C % B I 


39 


[+X]! 


Indirect store into RAM 
addressed by the 
pre-incremented X register 


E ( n - ) 
R(-) 

X:=X+1 Y:=Y 


1 





3A 


[X-]! 


Indirect store into RAM 
addressed by the 
post-decremented X register 


E ( n - ) 
R(-) 

X:=X-1 Y:=Y 


1 





3B xx 


[>X]! $xx 


Direct store into RAM 
addressed by the X register 


E ( n - ) 
R(-) 

X:=$xx Y:=Y 


2 





3C 


[Y]! 


Indirect store into RAM 
addressed by the Y register 


E ( n - ) 
R(-) 
X:=X Y:=Y 


1 





3D 


[+Y]! 


Indirect store into RAM 
addressed by the 
pre-incremented Y register 


E ( n - ) 
R(-) 

X:=X Y:=Y+1 


1 





3E 


[Y-]! 


i i 1 ■ i ■ i— » iii 

Indirect store into RAM 
addressed by the 
post-decremented Y register 


E ( n - ) 
R(-) 
X:=X Y:=Y-1 


1 





3F xx 


[>Y]I $xx 


Direct store into RAM 
addressed by the Y register 


E ( n - ) 
R(-) 

X:=X Y:=$xx 


2 





70 


SP@ 


Fetch the current Expression 
Stack Pointer 


E(--SPh SPI+1 ) 
R ( - ) 
SP:=SP+2 


2 




71 


RP@ 


Fetch the current Return Stack 
Pointer 


E ( - RPh RPI ) 

R(-) 


2 




72 


X@ 


Fetch the current X register 
contents 


E ( -- Xh XI) 
R ( - ) 


2 




73 


Y@ 


Fetch the current Y register 
contents 


E ( -- Yh Yl ) 
R(-) 


2 





74 


SP! 


Move the address into the 
Expression Stack Pointer 


E ( dh dl -- ? ) 

R(-) 

SP:=dh_dl 


2 





75 


RP! 


Move the address into the 
Return Stack Pointer 


E ( dh dl -- ) 
R ( - ? ) 
RP:=dh_dl 


2 




76 


X! 


Move the address into the X 
register 


E ( dh dl - ) R ( -- ) 
X:=dh_dl 


2 




77 


Y! 


Move the address into the Y 
register 


E ( dh dl - ) R ( -- ) 
Y:=dh_dl 


2 




78 xx 


>SP $xx 


Set the Expression Stack 
Pointer 


E I - ) R ( -- ) 
SP:=$xx 


2 




79 xx 


>RP $xx 


Set the return Stack Pointer 
direct 


E ( -- ) R ( - ) 
RP:=$xx 


2 




7A xx 


>X $xx 


Set the RAM address 
register X direct 


E ( - ) R ( - ) 
X:=$xx 


2 




7B xx 


>Y $xx 


Set the RAM address 
register Y direct 


E ( - ) R ( - ) 
Y:=$xx 


2 
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Table 2-2. Instruction Set (Continued) 



Code 
[hex] 


Mnemonic 


Operation 


Symbolic Description [Stack Effects] 


Instr. 
Cycles 


Flags 
C % B I 


7C 


NOP 


No operation 


PC:=PC+1 


1 




7D..7F 


NOP 


Illegal instruction 


PC:=PC+1 


1 





4x xx 


CALL $xxx 


Unconditional long CALL 


E ( ~ ) R ( - PC+2 ) 
PC:=$xxx 


3 




5x xx 


BRA $xxx 


Conditional long branch 


If B=1 then PC:=$xxx 
else PC:=PC+1 


2 


- - 1 - 
--0- 


6n 


LIT_n 


Push literal/constant n onto 
TOS 


E ( - n ) R ( - ) 


1 




80..BF 


SBRA $xxx 


Conditional short branch in 
page 


If B=1 then PC:= $xxx 
else PC:=PC+1 


2 




C0..FF 


SCALL $xxx 


Unconditional short CALL 


E (-)R(- PC+1 ) 
PC:= $xxx 


2 
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Table 2-3. MARC4 Instruction Set Overview 



Mnemonic 


Description 


Cycles/Bytes 


Arithmetic Operations 


ADD 


Add 


1/1 


ADDC 


Add with carry 


1/1 


SUB 


Subtract 


1/1 


SUBB 


Subtract with borrow 


1/1 


DAA 


Decimal adjust 


1/1 


INC 


Increment TOS 


1/1 


DEC 


Decrement TOS 


1/1 


DECR 


Decrement. 4-bit index on Return Stack 


2/1 


Compare Operations 


CMP_EQ 


Compare equal 


1/1 


CMP_NE 


Compare not equal 


1/1 


CMP_LT 


Compare less than 


1/1 


CMP_LE 


Compare less equal 


1/1 


CMP_GT 


Compare greater than 


1/1 


CMP_GE 


Compare greater equal 


1/1 


Logical Operations 


XOR 


Exclusive OR 


1/1 


AND 


AND 


1/1 


OR 


OR 


1/1 


NOT 


1's complement 


1/1 


SHL 


Shift left into carry 


1/1 


SHR 


Shift right into carry 


1/1 


ROL 


Rotate left through carry 


1/1 


ROR 


Rotate right through carry 


1/1 


Flag Operations 


TOG_BF 


Toggle Branch flag 


1/1 


SET_BFC 


Set Branch flag 


1/1 


Dl 


Disable all interrupts 


1/1 


CCR! 


Store TOS into CCR 


1/1 


CCR@ 


Fetch CCR onto TOS 


1/1 


Program Branching 


BRA $xxx 


Conditional long branch 


2/2 


CALL $xxx 


Long call (current page) 


3/2 


SBRA $xxx 


Conditional short branch 


2/1 


SCALL$xxx 


Short call (zero page) 


2/1 


EXIT 


Return from subroutine 


2/1 


RTI 


Return from interrupt 


2/1 


SWI 


Software interrupt 


1/1 


SLEEP 


Activate Sleep mode 


1/1 


NOP 


No operation 


1/1 
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Table 2-3. MARC4 Instruction Set Overview (Continued) 



Mnemonic 


Description 


Cycles/Bytes 


Register Operations 


SP@ 


Fetch the current SP 


2/1 


RP@ 


Fetch the current RP 


2/1 


X@ 


Fetch the contents of X 


2/1 


Y@ 


Fetch the contents of Y 


2/1 


SP! 


Move the top 2 into SP 


2/1 


RP! 


Move the top 2 into RP 


2/1 


X! 


Move the top 2 into X 


2/1 


Y! 


Move the top 2 into Y 


2/1 


>SP $xx 


Store direct address to SP 


2/2 


>RP $xx 


Store direct address to RP 


2/2 


>X $xx 


Store direct address into X 


2/2 


>Y $xx 


Store direct address into Y 


2/2 


Stack Operations 


SWAP 


Exchange the top 2 nibbles 


1/1 


OVER 


CopyTOS-1 to the top 


1/1 


DUP 


Duplicate the top nibble 


1/1 


ROT 


Move TOS-2 to the top 


3/1 


DROP 


Remove the top nibble 


1/1 


>R 


Move the top nibble onto the Return Stack 


1/1 


2>R 


Move the top 2 nibbles onto the Return Stack 


3/1 


3>R 


Move the top 3 nibbles onto the Return Stack 


4/1 


R@ 


Copy 1 nibble from the Return Stack 


1/1 


2R@ 


Copy 2 nibbles from the Return Stack 


2/1 


3R@ 


Copy 3 nibbles from the Return Stack 


4/1 


DROPR 


Remove the top of the Return Stack (12-Bit) 


1/1 


LIT_n 


Push immediate value (1 nibble) onto TOS 


1/1 


ROM Data Operations 


TABLE 


Fetch 8-bit constant from ROM 


3 


Memory Operations 


[X]@ 
[Y]@ 


Fetch 1 nibble from RAM indirectly addressed by X- or Y-register 


1/1 


[+X]@ 
[+Y]@ 


Fetch 1 nibble from RAM indirectly addressed by 
pre-incremented X- or Y-register 


1/1 


[X-]@ 
[Y-]@ 


Fetch 1 nibble from RAM indirectly addressed by 
post-decremented X- or Y- register 


1/1 


[>X]@ $xx 
[>Y]@ $xx 


Fetch 1 nibble from RAM directly addressed by X- or Y-register 


2/2 


[X]! 
[Y]! 


Store 1 nibble into RAM indirectly addressed by [X] 


1/1 


[+X]! 
[+Y]! 


Store 1 nibble into RAM indirectly addressed by 
pre-incremented [X] 


1/1 
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Table 2-3. MARC4 Instruction Set Overview (Continued) 



Mnemonic 


Description 


Cycles/Bytes 


[X-]! 
[Y-]! 


Store 1 nibble into RAM indirectly addressed by 
post-decremented X- or Y- register 


1/1 


[>X]! $xx 
[>Y]! $xx 


Store 1 nibble into RAM directly addressed by X- or Y- register 


2/2 


I/O Operations: 


IN 


Read l/O-Port onto TOS 


1/1 


OUT 


Write TOS to I/O port 


1/1 
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Section 3 



Programming in qFORTH 



3.1 Language • Expandability: Many of the Fundamental qFORTH Operations are Directly Implemented 

Features m tne MARC4 Instruction Set 

• Stack Oriented: All Operations Communicate with One Another via the Data Stack and 
Use the Reverse Polish Form of Notation (RPN) 

• Structured Programming: qFORTH Supports Structured Programming 

• Re-entrant: Different Service Routines can Share the Same Code, as Long as Global 
Variables are Not Modified within this Code 

• Recursive: qFORTH Routines Can Call Themselves 

• Native Code Inclusion: In qFORTH There is No Separation of High Level Constructs from 
the Native Code Mnemonics 



Programming in qFORTH reduces the software development time! 

Atmel's strategy in developing an integrated programming environment for qFORTH 
was to free the programmer from restrictions imposed by many FORTH environments 
(e.g., screen, fixed file block sizes), and at the same time to maintain an interactive 
approach to program development. The MARC4 software development system enables 
the MARC4 programmer to edit, compile, simulate and/or evaluate a program code 
using an integrated package with predefined key codes and pull-down menus. The com- 
piler-generated MARC4 code is optimized for demanding application requirements, 
such as the efficient usage of available program memory. One can be assured that the 
generated code only uses the amount of on-chip memory that is required, and that no 
additional overhead is attached to the program at the compilation phase. 

What other reasons are there for programming in qFORTH? 

Subroutines that are kept short increase the modularity and program maintainability. 
Both are related to the development cost. Programs that are developed using the Brute 
Force approach (where the program is realized in software using a sequential code) 
tend to be considerably larger in memory consumption, and are extremely difficult to 
maintain. 



3.2 Why Program in 
qFORTH 
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A qFORTH program, engineered using the building block modular approach is compact 
in size, easy to understand and thus, easier to maintain. The added benefit for the user 
is a library of software routines which can be interchanged with other MARC4 applica- 
tions as long as the input and output conditions of your code block correspond. This 
toolbox of off-the-shelf qFORTH routines grows with each new MARC4 application and 
reduces the amount of programming effort required. Programming in qFORTH results in 
a re-usable code. Re-usable for other applications which will be programmed at a later 
date. This is an important factor in ensuring that future software development costs are 
kept to a minimum. Routines written by one qFORTH programmer can be easily incor- 
porated by a different qFORTH user. 



3.3 



Language 
Overview 



qFORTH is based on the FORTH-83 language standard, the qFORTH compiler gener- 
ates a native code for a 4-bit FORTH-architecture single-chip microcomputer - Atmel's 
MARC4. 

MARC4 applications are all programmed in qFORTH which is designed specifically for 
efficient real-time control. Since the qFORTH compiler generates highly optimized 
codes, there is no advantage or point in programming the MARC4 in assembly code. 
The high level of code efficiency generated by the qFORTH compiler is achieved by the 
use of modern optimization techniques such as branch-instruction size minimization, 
fast procedure calls, pointer tracking and peephole optimizations. 



Figure 3-1. Program Development with qFORTH 



3-2 
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Standard FORTH operations which support string processing, formatting and disk I/O 
have been omitted from the qFORTH system library since these instructions are not 
required in single-chip microcomputer applications. 

The following two tables highlight the basic constructs and compare qFORTH with the 
FORTH-83 language standard. 



Table 3-1. qFORTH's FORTH-83 Language Subset 



Arithmetic/Logical 


Stack Operations 


- D+ 1+ AND NEGATE + D- 1- NOT 
DNEGATE * 2* D2* OR / 21 D2/ XOR 


>R <ROT ?DUP OVER 2DUP 1 R> 2DROP 
DEPTH DUP PICK 20VER DROP SWAP 
2SWAP J ROT ROLL 


Compiler 


Control Structure 


ALLOT $INCLUDE CONSTANT 
2CONSTANT CODE END-CODE 
VARIABLE 2VARIABLE 


?DO DO IS ELSE THEN +LOOP LEAVE UNTIL 
AGAIN ENDCASE LOOP WHILE BEGIN 
ENDOF OF CASE EXIT REPEAT EXECUTE 


Comparison 


Memory Operations 


< = <><= >= 0= 0<> D> D0<> D< D0= D>= 
D= MIN MAX DMIN DMAX D<= Do 


! 2! @ 2@ ERASE MOVE MOVE > FILL 
TOGGLE 



Table 3-2. Differences between qFORTH and FORTH-83 



Arithmetic/Logical 


Stack Operations 


4-bit Expression Stack 

12-bit Return Stack 

The prefix "2" on a keyword 

(e.g. 2DUP refers to an 8-bit data type) 

Branch and Carry flag in the Condition Code 

Register 

Only predefined data types for handling 
untyped memory blocks, arrays or tables of 
constants 


16-bit Expression Stack 

16-bit Return Stack 

The prefix "2" on a keyword 

(e.g. 2DUP refers to a 32-bit data type) 

Flag value on top of the Expression Stack 

CREATE, >BUILD .. DOES 



3.4 



The qFORTH 
Vocabulary 



3.4.1 



Word Definitions 



qFORTH is a compiled language with a dictionary of predefined words. Each qFORTH 
word contained in the system library has, as its basis, a set of core words which are very 
close to the machine-level instructions of the MARC4 (such as XOR, SWAP, DROP and 
ROT). Other instructions (such as D+ and D+!) are qFORTH word definitions. The 
qFORTH compiler parses the source code for words which have been defined in the 
system dictionary. Once located as being in the dictionary, the compiler then translates 
the qFORTH definition into MARC4 machine-level instructions. 

A new word definition which i.e. contains three sub-words: WORD1, WORD2 and 
WORD3 in a colon definition called MASTER-WORD is written in qFORTH as: 

: MASTER-WORD WORDl WORD 2 WORD 3 ; 

The colon ":" and the semicolon ";" are the start and stop declarations for the definition. 
A qFORTH programmer refers to a colon definition to specify a word name which fol- 
lows the colon. The following diagram depicts the execution sequence of these three 
words: 

The sequential order shows the way the compiler (and the MARC4) will understand 
what the program is to do. 
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1 St step 
2nd step 
3rd step 



4th step 



Begin the word definition with a followed by a space. 
Specify the <name> of the colon definition. 

List the names of the sequentially-organized words which will perform the 
definition. Remember that each word as shown above can itself be a colon 
or macro definition of other qFORTH words (such as D+ or 2DUP). 
Specify the end of the colon definition with a semicolon. 



Figure 3-2. Threaded qFORTH Word Definition 



: MASTER_WORD 



























WORD3 










WORD1 






WORD2 

















3.5 Stacks, RPN and 
Comments 

3.5.1 Reverse Polish 
Notation 



3.5.2 qFORTH Stacks 



3.5.3 



Stack Notation 



In this section, we will look at the qFORTH notation known as RPN. Other topics to be 
examined include qFORTH's stacks, constants and variables. 

qFORTH is a Reverse Polish Notation language (RPN), which operates on a stack of 
data values. RPN is a stack based representation of a mathematical problem where the 
top two numbers on the stack are operated on by the operation to be performed. 



Example: 
4 + 2 

42 + 



Is spoken in the English language as "4 plus 2", resulting in the value 6. In 
our stack-based MARC4, we write this using qFORTH notation as: 
The first number, 4, must be placed onto the data stack, then the second 
number will follow it onto the data stack. The MARC4 then comes to the 
addition operator. Both the 4 and 2 are taken off the data stack and pro- 
cessed by the MARC4's arithmetic and logic unit, the result (in this case 6) 
will be deposited onto the top of the data stack. 

The MARC4 processor is a stack-based microcomputer. It uses a hardware-constructed 
storage area onto which data is placed in a last-in-first-out nature. 

The MARC4 has two stacks, the Expression Stack and the Return Stack. 

The Expression Stack, also known as the Data Stack, is 4 bits wide and is used for 
temporary storage during calculations or to pass parameters to words. 

The Return Stack is 12 bits wide and is used by the processor to hold the return 
addresses of subroutines, so that upon completion of the called word, program control is 
transferred back to the calling qFORTH word. The Return Stack is used by all colon def- 
initions (i.e. CALLs), interrupts and to hold loop-control variables. 

The qFORTH stack notation shows the stack contents before and after the execution of 
a qFORTH word. The before and after operations are separated via two bars: - . The 
left hand side of the stack shows the stack before execution of the operation. The right 
most element before the two bars on the left side is the top of stack before the operation 
and the right most on the right side is also the top of stack after the operation. Examine 
the following qFORTH stack notation: 
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Table 3-3. Stack Notation 



Before Side 


After Side 


Example 


Stack Notation 


( n3 n2 n1 - 


n3 n2 n1) 


4 2 1 


(-421) 


T 


T 


+ 


(421-43) 


TOS 


TOS 


SWAP 


(43-34) 



3.5.4 Comments Comments in qFORTH are definitions which instruct the qFORTH compiler to ignore the 

text following the comment character. The comment is included in the source code of 
your program to aid the programmer in understanding what the code does. There are 
two types of comment declarations: 



qFORTH Comment Definitions 

Type _ 1 : ( text ) 
Type _ 2 : \ text 

Type_1 Comments begin and end with curved brackets while Type_2 comments 
require only a backslash at the beginning of the comment. Type_1 declara- 
tions do not require a blank space before closing the bracket. 

Type_2 Comments start at the second space following the backslash and go till the 
end of the line. Both types of declarations require a blank space to follow 
the comment declaration. 



Table 3-4. Comments 



Valid 


Invalid 


( this is a valid comment ) 


(this is not a valid comment) 


\ this is a valid comment 


\\ this is not a valid comment 



3.6 Constants and In qFORTH, data is normally manipulated as unsigned integer values, either as memory 
Variables addresses or as data values. 

3.6.1 Constants A constant is an unalterable qFORTH definition. Once defined, the value of the constant 

cannot be altered. In qFORTH, 4-bit and 8-bit numerical data can be assigned to a more 
readable symbolic representation. 



Table 3-5. Constant Definitions 



qFORTH Constant Definitions 


value CONSTANT <constant-name> 


( 4-bit constant ) 


value 2CONSTANT <constant-name> 


( 8-bit constant ) 



Example: 

7 CONSTANT Set -Mode 

42h 2 CONSTANT ROM_Okay 



: Load-Answer ROM_Okay; (Places 42h on EXP stack) 
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3.6.1.1 Predefined 
Constants 



In the qFORTH compiler a number of constants have a predefined function. 
$ROMSIZE 

2CONSTANT to define the MARC4's actual ROM size. The values are 1.5K (default), 
2.0K, 2.5K, 3.0K and 4.0 Kbytes of ROM. 

$RAMSIZE 

2CONSTANT to define the MARC4's actual RAM size in nibbles. Possible values are 
111 (default), 167 and 255 nibbles. 

$EXTMEMSIZE 

Allows the programmer to define the size of an external memory. Only required if an 
external memory is used whereby the default value is set at 255 nibbles. 

$EXTMEMPORT 

Allows the definition of a port address via which the external memory is accessed. The 
default port address for external memory is Fh. 

$EXTMEMTYPE 

Allows the definition of the type of external memory used. The types RAM or EEPROM 
are valid, whereby RAM is default if an external memory is used. 

Example: 



6 

RAM 

95 

16 



CONSTANT 
CONSTANT 
2 CONSTANT 
2 ARRAY 



$EXTMEMPORT 
$ EXTMEMTYPE 
$ EXTMEMS I Z E 
Freq EXTERNAL 
80h D> 



Check_Freq Freq [4] 2@ 

IF 0 0 Frequency [5] 2! 
THEN 



3.6.2 Look-up Tables Look-up tables of 8-bit bytes are defined by the word ROMCONST followed by the 

<table-name> and a list of single- or double-length constants each delimited by a space 
and a comma. 

The content of a table is not limited to literals such as 5 or 67h, but may also include 
user- or pre-defined constants such as Set-Mode or ROM_Okay. 

In the examples below, the days of the month are placed into a look-up table called 
"Days_Of_Month", the month (converted to 0 ... 11) is used to access the table in order 
to return the BCD number of days in the given month. 



Table 3-6. Table Definitions 


qFORTH Table Definitions 


ROMCONST <table-name> 


Const , Const , Const 




Const , Const , Const 
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Examples: 

ROMCONST DaysOf Month 3 lh , 2 8h , 3 In , 3 Oh , 

31h , 30h , 31h , 31h , 

30h , 31h , 30h , 31h , 

ROMCONST DaysOf Week SU , MO , TU , WE , TH , FR , SA 

ROMCONST Message 11 , " Hello World " , 

Notes: 1 . A comma must follow the last table item. 

2. Since there is no end-of-table delimiter in qFORTH, only a colon definition, a VARI- 
ABLE or another ROMCONST may follow a table definition (i.e. the last comma). 



3.7 Variables and A variable is a qFORTH word whose name is associated with a memory address. A 
Arrays value can be stored at the memory address by assigning a value to the named variable. 

The value at this address can be accessed by using the variable name, thereby placing 
the variable value onto the top of the stack. 

The VARIABLE definition has a 4-bit memory cell allocated to it. qFORTH also permits 
a double-length 8-bit value to be assigned as a 2VARIABLE. 



Table 3-7. Variable Definitions 



qFORTH Variable Definitions 


VARIABLE <variable-name> 


4-bit variable 


2VARIABLE <variable-name> 


8-bit variable 



Example: 

VARIABLE Relay* 



2 VARIABLE Voltage 

3.7.1 Defining Arrays qFORTH arrays are declared differently from arrays in FORTH-83. In both implementa- 
tions of FORTH an array is a collection of elements assigned to a common name. An 
array can either be defined as being a VARIABLE with 8 elements: 

VARIABLE DATA 7 ALLOT 

or using the qFORTH array implementation: 

8 ARRAY DATA 

The array index is running from 0 to <length-1>. 

ARRAY and 2ARRAY may contain up to 16 elements (e.g. nibbles or bytes). LARRAY 
and 2LARRAY contain more than 16 elements. 



Table 3-8. Array Definitions 



qFORTH Array Definitions 


ARRAY 


Allocates RAM space for a short 4-bit array 


LARRAY 


Allocates RAM space for a long 4-bit array 


2ARRAY 


Allocates space for a short 8-bit array 


2 LARRAY 


Allocates space for a long 8-bit array 



MARC4 4-bit Microcontrollers Programmer's Guide 



3-7 



4747A-4BMCU-01/04 



Programming in qFORTH 



3.8 



Stack Allocation 



3.8.1 



Stack Pointer 
Initialization 



Both the Expression and Return Stacks are located in RAM. The size of the stacks is 
variable and must be defined by the programmer by using the predefined variables RO 
and SO. 

Figure 3-3 shows the location of the stacks in RAM. The Return Stack variable address 
RO starts at RAM location OOh. The Expression Stack is located above the Return Stack, 
starting at the next location called SO. 

The depth of the Expression and Return Stacks is allocated using the ALLOT construct. 
While the depth (in nibbles) of the Expression Stack is exactly the number allocated, the 
Return Stack depth is expressed by the following formula: 

RET_Value := RET_Depth x 4 

Example: 

VARIABLE RO 2 0 ALLOT \ RET Depth of 5 
VARIABLE SO 17 ALLOT \ EXP Depth of 17 

Figure 3-3. Stacks Inside RAM 

RAM 
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0 


0 


0 




DC 



Auio-Sleep 



The two stack pointers must be initialized in the $RESET routine. 

Note: The Return Stack pointer RP must be set to FCh so that the AUTOSLEEP feature will 
work. 
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Example: 

VARIABLE RO 32 ALLOT \ RET stack depth = 8 
VARIABLE SO 12 ALLOT \ EXP stack depth = 12 nibbles 
: $ RESET 

>RP FCh \ Initialize the two stack pointers 

>SP SO 

RAM_Test 



3.9 Stack 

Operations, 
Reading and 
Writing 



3.9.1 Stack Operations A number of stack operators are available to the qFORTH programmer. An overview of 

all the predefined stack words can be found in the "qFORTH Quick Reference Guide". 
Stack operators used most often and which manipulate the order of the elements on the 
Data Stack like DUP, DROP, SWAP, OVER and ROT are explained later on. 

3.9.1 .1 Data Stack The 4-bit wide Data Stack is called the Expression Stack. Arithmetic and data manipula- 

tion are performed on the Expression Stack. The Expression Stack serves as a holding 
device for the data and also as the interface link between words, so that all data passed 
between the qFORTH words can be located on the Expression Stack or in global 
variables. 

The qFORTH word 

: TEN 1234567890; 

Figure 3-4. Push-down Data Stack 

1 i TOS 

0 

9 T0S - 1 
8 



6 

5 

4 

3 

2 + 

1 TOS-9 



When executed, the value 0 at the top and the value 1 at the bottom of the Expression 
Stack will be the result. 
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3.9.1.2 SWAP In many programming applications it is necessary to re-arrange the input data so that it 

can be handled properly. For example we will use a simple series of data and then 
SWAP them so that they appear in the reserve order. 

4 2 SWAP (4 2-2 4) 

Figure 3-5. The SWAP Operation 




Expression Stack 



Expression Stack 



3.9.1.3 DUP, OVER and The qFORTH word to duplicate the TOS item is DUP. It will make a copy of the current 
DROP TOS element on the Expression Stack. 

DUP is useful in retaining the TOS value before operations which implicitly DROP the 
TOS following their execution. For example, all of the comparison operations like >, >=, 
<= or < destroy the TOS. 

The OVER operation makes a copy of the second element on the stack (TOS-1) and 
deposits it onto the top of the stack. 

The MARC4 stack operator DROP removes one 4-bit value from the TOS. For example, 
the qFORTH operation NIP will drop the TOS-1 element from the stack. This can be 
written in qFORTH as: 

: NIP SWAP DROP ; ( nl n2 -- n2 ) 

3.9.1.4 ROT and <ROT Stack values must frequently be arranged into a defined order. We have already been 

introduced to the SWAP operation. Apart from SWAP, qFORTH supports the stack rota- 
tion operators ROT and <ROT. 

The ROT operation moves the third value (TOS-2) to the TOS. The operation <ROT 
(which is the same as ROT ROT) does the opposite of ROT, moving the value from the 
TOS to the TOS-2 location on the Expression Stack. 

qFORTH also supports data transfers between the Expression and the Return Stack. 

The >R operation moves the top 4-bit value from the Expression Stack and pushes the 
value onto the Return Stack. R> removes the top 4-bit value from the Return Stack and 
puts the value onto the Expression Stack, while R@ (or I) copies the 4-bit value from the 
Return Stack and deposits the copied value onto the Expression Stack. DROPR 
removes the top entry from the Return Stack. 



3.9.1.5 R>, >R, R@ and 
DROPR 
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Figure 3-6. Return Stack Data Transfers 



TOS 
TOS-1 



TOS-9 



R>, R@, I 



>R, #DO 



Expression Stack 



Return Stack 



3.9.1.6 Other Useful Stack The following list contains more useful stack operations. Note that for every 4-bit stack 
Operations operation, there is almost always an 8-bit equivalent. A full list of all stack operations 

may be found in section 4.6 "The qFORTH Language - Quick Reference Guide". 



' <name> 


EXP ( 


-- ROMAddr ) 


Places ROM address of colon-definition 








<name> on EXP stack 


<ROT 


EXP ( 


n1 n2 n - n n1 n2 ) 


Move top value to 3rd stack pos 


?DUP 


?DUP 


EXP ( n -- n n ) 


Duplicate top value if n <>0 


I 


EXP ( 


-I) 


Copy 4-bit loop index I from the return to the 








Expression Stack 


l""> f7S\ 

R@ 


RET ( 


u u I - u u I ) 




NIP 


EXP ( 


n1 n2 - n2 ) 


Drop second to top 4-bit value 


TUCK 


EXP ( 


n1 n2 - n2 n1 n2 ) 


Duplicate top value, move under second 








item 


2>R 


EXP ( 


n1 n2 -- ) 


Move top two values from Expression to 




RET ( 


-- u | n2 n1 ) 


Return Stack 


2DROP 


EXP ( 


n1 n2 -- ) 


Drop top 2 values from the stack 


2DUP 


EXP ( 


d - d d ) 


Duplicate top 8-bit value 


2NIP 


EXP ( 


d1 d2 - d2 ) 


Drop 2nd 8-bit value from stack 


20VER 


EXP ( 


d1 d2 -- d1 d2 d1 ) 


Copy 2nd 8-bit value over top value 


2<ROT 


EXP ( 


d1 d2 d - d d1 d2 ) 


Move top 8-bit value to 3rd position 


2R> 


EXP ( 


-- n1 n2 ) 


Move top 8 bits from Return to Expression 




RET ( 


u n2 n1 - ) 


Stack 


2R@ 


EXP ( 


-- n1 n2 ) 


Copy top 8 bits from Return to Expression 




RET(u| n2| n1-u| n2 1 n1) Stack 


3>R 


EXP ( 


n1 n2 n3 -- ) 


Move top 3 nibbles from the Expression onto 




RET ( 


-- n3 1 n2 n1 ) 


the Return Stack 


3DROP 


EXP ( 


n1 n2 n3 - ) 


Remove top 12-bit value from stack 


3DUP 


EXP ( 


t-tt) 


Duplicate top 12-bit value 


3R> 


EXP ( 


-- n1 n2 n3 ) 


Move top 3 nibbles from Return to the 




RET ( 


n3 n2 n1 - ) 


Expression Stack 


3R@ 


EXP ( 


-- n1 n2 n3 ) 


Copy 3 nibbles (1 ROM address entry) from 




RET 




the Return Stack to the Expression Stack 




( n3 1 


n2 1 n1 -- n3 1 n2 n1 ) 
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3.9.2 Reading and Writing 

(©,!) 



In the previous section it was mentioned that data can be placed onto, and taken off the 
Expression Stack. 

The reading and writing operations transfer data values between the data stack and the 
RAM. Writing a data value to a RAM location which has been specified by a variable 
name requires the TOS to contain the variable's 8-bit RAM address and that the data to 
be stored in the RAM be contained at the TOS-2 location. 

The read operator is written in the qFORTH syntax with the @ symbol and is pro- 
nounced fetch. The write operator is written in qFORTH with the ! symbol and is 
pronounced store. 

To write two qFORTH colon definitions (words) that will store the numeric value 7 from 
the TOS to the variable named FRED and then fetch the contents its back onto the 
Expression Stack (TOS). 

Example: 

VARIABLE FRED 



Store 
Fetch 



7 FRED ! 
FRED 



@ ; 



( 



For 8-bit values, stored at two consecutive locations, qFORTH has the Double-Fetch 
and Double-Store words: 2@ and 2!. To store 1 Ah in the 8-bit 2VARIABLE BERT using 
the Double-Store, examine the following code: 



2 VARIABLE BERT 
: Double-Store 



lAh 



BERT 



2 ! 



Storing the value 1 Ah is a two-part operation: The high-order nibble 1 is stored in the 
first digit, while at the next 4-bit RAM location the hexadecimal value A will be stored. 



Double -Fetch 



BERT 



2@ 



d) 



3.9.3 Low-level Memory 
Operations 



i.e., accesses the 8 bits at the memory address where BERT is placed and loads them 
onto the Expression Stack. The lower-order nibble will always end up on TOS. 

Note: Hexadecimal values are represented by an h or H following the value. 



3.9.3.1 RAM Address 

Registers X and Y 



The MARC4 processor can address any location in RAM indirectly via the 8-bit wide X 
and Y RAM Address Registers. These registers are used as pointer registers to orga- 
nize arrays within the RAM. They can be pre-incremented or post-decremented by using 
CPU control. 

The X and Y registers are automatically used by the compiler during fetch (@) and store 
(!) operations. Hence, care should be taken when referencing these registers explicitly. 
If a default occurs, the compiler uses the Y register. 
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Table 3-9. Memory Operators which Use the X/Y Register 



Memory Operators which Use the X/Y Register 




U+! 


O 1 


bHAbb 


! 


D-! 


2@ 


FILL 


+! 


TD+! 


3! 


MOVE 


1+! 


TD-! 


3@ 


MOVE> 


-! 


T+! 


PICK 


TOGGLE 


1-! 


T-! 


ROLL 


DTOGGLE 



Example: 

The 4-bit value in TOS is added to an 8-bit RAM value and stored back into the 8-bit 
RAM variable. 



: M+ ! ( n RAM_addr - ) 

X! [+X] @ + [X-] ! 

0 [X] @ +C X] ! 



2 VARIABLE Voltage 
5 Voltage M+ ! 



Table 3-10. Low Level Memory Operation 



X Register 


Description 


Y Register 


X@ 


Fetch current X (or Y) register contents 


Y@ 


X! 


Move 8-bit address from stack into X (or Y) register 


Y! 


>X xx 


Set register address of X (or Y) directly 


>Y yy 


[>X]@ xx 


Directly RAM fetch, X (or Y) addressed 


[>Y]@ yy 


[>X]! xx 


Directly RAL store, X (or Y) addressed 


[>Y]I yy 


[X]@ 


Indirectly X (or Y) fetch of RAM contents 


[Y]@ 


[X]! 


Indirectly X (or Y) store of RAM contents 


[Y]l 


[+X]@ 


Pre-increment X (or Y) indirect RAM fetch 


[+Y]@ 


[X-]@ 


Post-decrement X (or Y) indirect RAM fetch 


[Y-]@ 


[+X]! 


Pre-increment X (or Y) indirect RAM store 


[+Y]I 


[X-]! 


Post-decrement X (or Y) indirect RAM store 


[Y-]l 
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3.9.3.2 Bit Manipulations in By using the X or Y registers, it is possible to manipulate the content of the RAM on a 
RAM bit-wise basis. The following examples all have the same stack notation. 

: BitSet ( mask RAM_addr - [branch flag] ) 

X! [X]@ ( get data from memory ) 
OR [X] ! ( mask & store in memory ) 



BitReset ( mask RAM_addr - [branch flag] ) 
X! 

Fh XOR ( Invert mask for AND ) 

[X]@ ( get data from memory ) 

AND [X] ! ( mask & store in memory ) 



TestO= ( mask RAM_addr - [branch flag] 

X! [X]@ 
AND DROP 



CODE TestOo ( mask RAM_addr - [branch flag] ) 

TestO= TOG_BF 
END-CODE 



3.10 MARC4 

Condition Codes 



The MARC4 processor has within its Arithmetic Logic Unit (ALU) a 4-bit wide Condition 
Code Register (CCR) which contains 4 flag bits. These are the Branch (B) flag, the 
Interrupt-Enable (I) flag and the Carry (C) flag. 

Figure 3-7. MARC4 Condition Code Register Flags 

T 



T 



B 



T 



_l_ 



CCR 

Interrupt Enable 
Branch 
(reserved) 
Carry 



Most arithmetic/logical operations, for example, will have an effect on the CCR. If you try 
to add 12 and 5, the Carry and Branch flags will be set, since an arithmetic overflow has 
occurred. 
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3.10.1 CCR and Control The Carry flag is set by ALU instructions such as the +, +C, - or -C whenever an arith- 
Operations metic under/overflow occurs. The Carry flag is also used during a shift/rotate instruction 

such as ROR and ROL. 

The Branch flag is set under CPU control, depending upon the current ALU instruction, 
and is a result of the logical combination of the Carry flag and the TOS = 0 condition. 

The Branch flag is responsible for generating conditional branches. The conditional 
branch is performed when the Branch flag has been set by one of the previous qFORTH 
operations (e.g., comparison operations). 

The TOG_BF instruction will toggle the state of the Branch flag in the CCR. If the 
Branch flag is set before the TOG_BF instruction, it will be reset following the execution. 

The SET_BCF instruction will set the Branch and Carry on execution, while the 
CLR_BCF operation will reset both flags. 



3.1 1 Arithmetic The arithmetic operators presented here are similar to those described in most FORTH 

Operations literature. The underlying difference, however, is that the qFORTH arithmetic operations 

are based on the 4-bit CPU architecture of the MARC4. 

3.11.1 Number Systems When coding in qFORTH, standard numeric representations are decimal values. For 

other representations, it is necessary to append a single character for that 
representation. 



Example: 



Bh 
bH 
11 

1011b 
1011B 



— > 

-» 
-» 
-» 



hexadecimal 

hexadecimal 

decimal 

binary 

binary 



base 16 ) 
base 16 ) 
base 10 ) 
base 2 ) 
base 2 ) 



3.1 1 .1 .1 Single- and Double- Examples have already been presented which perform operations on the TOS as a 4-bit 
length Operators (single-length) value or on both the TOS and TOS-1 values. By combining the TOS and 
TOS-1 locations, it is possible to handle the data as an 8-bit value. 

Note: In qFORTH, all operators which start with a 2 (e.g: 2SWAP or 2@) use double-length (8- 
bit) data. Other operators such as D+ and D= are also double-length operators. 

The qFORTH language also permits triple-length operators, which are defined with a 3 
prefix (e.g: 3DROP). Examples for all qFORTH dictionary words are included in 
section 4 "qFORTH Language Dictionary". 

3.11.2 Addition and The algebraic expression 4 + 2 is spoken in the English language as: 4 plus 2, and 

Subtraction results in a value of 6. In qFORTH, this expression as 4 2 +. The 4 is deposited onto the 

Data Stack, followed by the 2. The operator gives a command to take the top two values 
from the Data Stack and add them together. The result is then placed back onto the 
Data Stack. Both the 4 and the 2 are dropped from the stack by the operation. 

The stack notation for the addition operator is: 

+ EXP ( nl n2 -- nl+n2 ) 
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qFORTH performs the subtraction in a similar way to the addition operator. The operator 
is the common algebraic symbol with the stack notation: 



EXP ( nl n2 



nl-n2 



Examples: 

: TNEGATE 

0 SWAP - 
0 ROT -c 
ROT 0 SWAP-c 
SWAP ROT 



12-bit 2's complement on the TOS ) 
th tm tl -- th tm -tl ) 
th tm -tl -- th -tl -tm ) 
th -tl -tm -- tl -tm -th ) 
-tl -tm -th -- -t ) 



3NEG! ( 12 -bit 2's complement in an array 

Y! 0 [+Y]@ 0 [+Y]@ ( addr -- 0 tm 0 tl ) 

- [ Y- ] ! -c [Y-] ! ( 0 tm 0 tl -- ) 

0 [Y] @ -c [Y] ! (0 tm -tl --) 



3.1 1 .3 Increment and 
Decrement 



Increment and decrement instructions are common to most programming languages. 
qFORTH supports both with the standard syntax: 



1+ increment new-TOS: = old-TOS + 1 
1- decrement new-TOS: = old-TOS -1 



3.11.4 Mixed-length 
Arithmetic 



Example: 



Inc-Dec 



Note: 



10 ( -- Ah ) 

1+ ( Ah -- Bh ) 

1-1- ; ( Bh -- 9h ) 

The Carry flag in the CCR is not affected by these MARC4 instructions, whereby the 
Branch flag is set if the result of the operation becomes zero. 



qFORTH supports mixed-length operators such as M+, M-, M* and M/MOD. In the 
examples below, a 4-bit value is added/subtracted to/from an 8-bit value (generating an 
8-bit result) using the M+ and M- operators. 



3.11.5 BCD Arithmetic 



Voltage 2@ 5 M+ 
IF 2 DROP 0 0 
ELSE 10 M- THEN 
Voltage 2 ! 



\ IF overflow, THEN reset Voltage 



3.11.5.1 DAA and DAS 



Decimal numbers are usually represented in 4-bit binary equivalents of each digit using 
the binary-coded-decimal coding scheme. The qFORTH instruction set includes the 
DAA and DAS operations for BCD arithmetic. 
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3.11.5.1.1 DAA Decimal adjust for BCD arithmetic, adds 6 to values between 10 and 15. It will also add 

6 to the TOS, if the carry flag is set. 

Fh ( 1111 )->5(0101 ) and carry flag set 

Eh(1110)->4(0100) 

Dh(1101 )->3(0011 ) 

Ch(1100)->2(0010) 

Bh(1011 )->1 (0001 ) 

Ah ( 1010 )-> 0(0000) 

3.11.5.1.2 DAS Decimal arithmetic for BCD subtraction, builds a 9's complement for DAA and ADDC, 

the branch and carry flags will be changed. 

Examples: 

: DIG- 

Y! SWAP DAS SWAP 
#D0 

[Y] @ + DAA [Y-] ! 

10 - ? LEAVE 
#L00P 
DROP 



\ Digit count LSD_Addr -- 

\ Generate 9 ' s complement 

\ Digit count -- Digit 

\ Transfer carry on stack 

\ Exit LOOP , if NO carry 

\ Repeat until index = 0 

\ Skip TOS overflow digit 



BCD_1+! \ RAM_Addr -- 

Y! [Y]@ \ Increments BCD digit 

1 + DAA [Y] ! \ in RAM array element 



: Array_l+ \ Inc BCD array by 1 

( n array [n] -- ) 

Y! SET_BCF ( Start with carry 

BEGIN 

[Y] @ 0 +C DAA [Y-] ! 

1- 
UNTIL 
DROP 
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3.11.6 Summary of The following list contain more useful arithmetic words. The full list and implementation 

Arithmetic Words may be found in the MATHUTIL.INC file 



U+ 


[ d1 d2 — d_sum 


) Add top two 8-bit elements 


U- 


1 ri-1 HO WO r4-i 

{ Qi CM. — 0^-01 


) Subtract top two 8-bit elements 


U+! 


[ nh nl addr — 


) Aau o-Dit I (Jo to memory 


U-! 


[ nn ni auur — 


) oUDtraci o-uii i uo irom rnerTiory 


IVI + 


| H1 n HO 


\ AHH A hit THQ tr\ an ft hit 

) Mud 4 - UlI 1 KJO IU all o - Ult ValUG 


Ivl- 


1 AA n HO 

[ ai n — Qd. 


\ Oi ih+*-<-»/-t+ A hit ~V(~\ O kv-» Q Kit will i r\ 

) oUDiracT 4-dii i uo Trom o-dit value 


WI+! 


{ n addr — 


) Aaa n to an o-Dit ham oyte 


nil i 
M-! 


[ n addr — 


) oUDtract n irom o-Dit riAM oyte 


ivji/ 
ml 


[ d n — d quotient 


) Divide n from d 


m 


[ d n — d_product 


) Multiply a Dy n 


M/MUU 


[ d n — n_quot n_rem 


) Divide n from d giving 4-bit results 


D/MOD 


( d n - d_quot n_rem 


) Divide 8-bit value & 4-bit remainder 


TD+! 


( d addr - 


) Add 8-bit TOS to 1 2-bit RAM var. 


TD-! 


( d addr - 


) Subtract 8-bit from 1 2-bit RAM var. 


TD+ 


( d addr - 1 


) Add 8-bit to 1 2-bit RAM var. 


TD- 


( d addr - 1 


) Subtract 8-bit from 1 2-bit RAM var. 


D->BCD (d-n_ 


100 n_10 n_1 


) Convert 8-bit binary to BCD 



3.12 Logicals The logical operators in qFORTH permit bit manipulation. The programmer can input a 

bit stream from the input port, transfer it onto the Expression Stack and then shift 
branches and the bit pattern left or right, or the bit pattern can be rotated onto the TOS. 
The Branch and Carry flag in the CCR are used by many of the qFORTH logical 
operators. 

3.12.1 Logical Operators The truth table shown below is the standard table used to represent the effects of the 

logical operators on two data values (n1 and n2). 

These qFORTH operators take the top values off of the Expression Stack and perform 
the desired logical operation. The resultant flag setting and the stack conditions are 
described in section 4 "qFORTH Language Dictionary". 

The stack notation for all logical qFORTH words is: 

EXP ( n1 n2 - n3 ) 
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Table 3-1 1. Logical Operations 



NOT 


OR 


AND 


XOR 


n1 


n1' 


n1 n2 n1 v n2 


n1 n2 n1 A n2 


n1 n2 n1 XOR n2 


1 


0 


0 0 0 


0 0 0 


0 0 0 


0 


1 


0 1 1 


0 1 0 


0 1 1 






1 0 1 


1 0 0 


1 0 1 






1 1 1 


1 1 1 


1 1 0 



As an example, examine the logical AND operation with the data values 3 and 5. Repre- 
senting these values in 4-bit binary, and performing the AND operator: 



0101b 0011b ( -- 0101b 0011b ) 
AND ( 0101b 0011b -- 0001b ) 



results in a value of 1 appearing on the TOS. The Branch flag will be reset, since the 
result of the logical operation is non-zero. 

Example: 

: Logicals 

3 7 OR 
3 7 AND 
5 XOR 
NOT 
2 DROP 



-- 7 

7 -- 7 3 

7 3 -- 7 6 

7 6 -- 7 9 
7 9-- 



3.12.1.1 TOGGLE The TOGGLE operation is classified in the section 4 "qFORTH Language Dictionary" as 

belonging to the set of memory operations. Although this is true, the TOGGLE and its 
relative, the DTOGGLE, are both used to change bit patterns at a specified memory 
address. For the TOGGLE operation the 4-bit value located at the specified memory 
location will be exclusive-ORed. 

Example: 

VARIABLE LED_Status 
: Toggle-LED 

0001b LED_Status TOGGLE ( toggles bit 0 only ) 

3.12.1.2 SHIFT and ROTATE The MARC4 instruction set contains two shift and two rotate instructions which are 
Operations shown in Table 3-12. The shift operators multiply (SHL) and divide (SHR) the TOS value 

by two. These instructions are identical to the qFORTH macros for 2* and 21. 

The rotate instructions ROR and ROL shift the TOS value right/left through the Carry 
flag, and cause the Carry and Branch flags to be altered. When using these instructions, 
it is advisable to set or reset the flags within your initialization routine, using either the 
SET_BCF or the CLR_BCF instructions. 
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Table 3-12. Shift and Rotate Instructions 



Mnemonic 



Description 



Function 



SHR 

2.1 



ROR 



SHL 

2* 



Shift TOS right into Carry 



3 2 10 



0 




1 1 1 
1 1 1 




c 



Rotate TOS right through 
Carry 



3 2 10 



n 1 1 - 

_i i i_ 



Shift TOS left into Carry 



c 




I I I 
1 1 1 




0 



ROL 



Rotate TOS left through Carry 



~i 1 r 

_i I i_ 



Example: 

Write the necessary qFORTH word definitions to flip a data byte (located on TOS) as 
shown below: 



Before flip: 3 2 10 
7 6 5 4 



After flip: 4 5 6 7 
0 12 3 



FlipBits 
0 

4 #DO 

SWAP SHR 
SWAP ROL 

#LOOP 

NIP 



FlipByte FlipBits SWAP FlipBits ; 
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3.13 Comparisons The qFORTH comparison operations (such as > or <) will set the Branch flag in the CCR 

if the result of the comparison is true. The stack effects of a comparison operation is: 

EXP ( nl n2 - ) 

3.13.1 < , > The qFORTH word < performs a "less-than" comparison of the top two values on the 

stack. If the second value on the Expression Stack is less than the value on the TOS, 
then the Branch flag in the CCR will be set. Following the operation, the stack will con- 
tain neither of the two values which where checked, as they will be dropped from the 
Expression Stack. 



: Less-Example 9 5 ( --95) 

< ; (95--) 

The > comparison operator determines if the second value on the stack is greater than 
the TOS value. If this condition is met, then the Branch flag will be set in the CCR. 

3.13.2 <= , >= Using <= in your qFORTH program enables you to determine if the second item on the 

stack is less or equal to the TOS value. 

In the GREATER-EQUAL example, the top two stack values 5 and 9 are removed from 
the stack and used as input values for the greater-or-equal operation. If the second 
value (TOS-1) is greater or equal the TOS value and subsequently the branch flag in the 
CCR will be set. 

After the comparison operation has been performed by the MARC4 processor, neither 
of the two input values will be contained on the Expression Stack. 



: GREATER- EQUAL 9 5 (--95) 

>= ; (95-- [C-B-] ) 

3.13.3 <> , = These two qFORTH comparison operators can be used to determine the Boolean 

(true/false) value (e.g. setting/resetting the Branch flag in the CCR). If the second value 
on the stack is not equal ( <> ) to the TOS value, then the Branch flag in the CCR will be 
set. The two values that were on the TOS before the operation, are dropped off the 
stack after the operation has been executed, except if one or both items on the Data 
Stack were duplicated before the operation. 

If, however, the equality test ( = ) is executed then the Branch flag will only be set, if both 
the TOS and the TOS-1 values are identical. Again, as with all the comparison opera- 
tions presented so far, the contents of the TOS and TOS-1 previous to the operations 
are dropped from the stack. 

3.13.4 Comparisons Using Example: 

8-bit Values 68 2constant par-for-course 

2VARIABLE GROSS-SCORE 
: Check-golf -score 

GROSS-SCORE2@PAR-FOR-COURSE D- 
0 8 D<= IF GOOD-SCORE THEN 

\ My Handicap is 8 



Note: There is a space between the 0 and 8. This is required because literals less then 16 are 
assumed to be 4-bit values. 
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This problem may be avoided if an additional 2CONSTANT is used, since 2CONSTANT 
assumes an 8-bit value, e.g. : 

8 2 CONSTANT My-Handicap 
: Check-Golf -score 

GROSS-SCORE 2@ PAR-FOR-COURSE D- 

My-Handicap D<= 

IF GOOD-SCORE THEN 



3.14 Control The control structures presented here can be divided into two categories: Selection and 

Structures looping. The Table 3-13 and Table 3-14 compare qFORTH's control structures will those 

found in PASCAL. 

As the comparison of the two languages shows, qFORTH offers a rich variety of struc- 
tures which enable your program to branch to different code segments within the 
program. 



Table 3-13. qFORTH Selection Control Structures 



qFORTH 


PASCAL 


<condition> 

IF <operation> THEN 

<condition> 

IF <operations> 

ELSE <operations> THEN 

<value> CASE .. 

<n> OF <operations> ENDOF .. 

ENDCASE 


IF <condition> 
THEN <statements> ; 

IF <condition> 
THEN <statements> 
ELSE <statements> ; 

CASE <value> .. 

<n> OF <statements> ; 

.. END ; 


Table 3-14. qFORTH Loop Control Structures 


qFORTH 


PASCAL 


BEGIN <operations> <condition> UNTIL 

BEGIN <condition> WHILE <operations> 
REPEAT 

BEGIN <operations> AGAINb 

<limit> <start> DO <operations> LOOP 

<limit> <start> DO <operations> <offset> + 
LOOP 

<limit> <start> DO <operations> <condition> 
7LEAVE <operations> LOOP 

<n-times> #DO 
<operations> #LOOP 


REPEAT <statements> UNTIL <condition> ; 
WHILE <condition> DO <statements> ; 

FOR i := <start> TO <limit> DO <statements> ; 

FOR i := <start> DOWNTO 0 DO 
<statements> ; 
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3.14.1 Selection Control The code to be executed is dependent on a specific condition. This condition can be 
Structures indicated by setting the Branch flag in the CCR. The control operation sequences such 

as the IF .. THEN and the indefinite loop operations such as BEGIN .. UNTIL and 
BEGIN .. WHILE .. REPEAT will only be executed if the Branch flag has been set. 

3.14.1.1 IF .. THEN The IF .. THEN construct is a conditional phrase permitting the sequence of program 

statements to be executed dependent on the IF condition being valid. The qFORTH 
implementation of the IF .. THEN phrase requires that the <condition> computation 
appears before the IF word. 

IF .. THEN in PASCAL : 

IF <condition> THEN < True statements> ELSE <False statements> ; 
IF .. THEN in qFORTH : 

<condition> IF <True operations> ELSE <False operations> THEN 



Example: 



GREATER- 9 
DUP 9 > 

DROP 
THEN 



IF 



(n 



n or 1, IF n > 9) 



1 (THEN replace n -- 1) 
(ELSE keep original n) 



$RESET 



>SP SO (Power-on initialization entry 

>RP FCh (Init both stack pointers first 

10 Greater-9 (Compare 10 > 9 ==> BF true 

5 Greater-9 (1 5 -- 1 5 

2 DROP (15 — 



The qFORTH word GREATER-9 checks if the values given on TOS as a parameter to 
the word are greater than 9. 

First the current TOS value is duplicated. Then, 9 is deposited onto the TOS so that the 
value to be compared to is now in the TOS-1 and TOS-2 location of our data stack. The 
TOS value is now compared with the TOS-1 value. IF TOS-1 is greater than 9, then the 
condition has been met. The qFORTH words following the IF will therefore be executed. 
In the first example the TOS value will be dropped and replaced by the value 1 . 

3.14.1.2 CASE Structure The CASE structure is equivalent to the IF .. ELSE .. THEN structure. The IF .. ELSE .. 

THEN permits nested combinations to be constructed in qFORTH. A nested IF .. ELSE 
.. THEN structure can look like this example: 
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: 2BIT-TEST 



DUP 0 = IF BITOOFF ELSE 
DUP 1 = IF BITOON ELSE 
DUP 2 = IF BIT10FF ELSE 
BITION 
THEN THEN THEN THEN 

DROP ; 

In the word "2BIT-TEST", the TOS is checked to see if it contains one of three possible 
values. If either one of these three values is on the TOS, then the desired word definition 
will be executed. If none of these three conditions has been met, then a fourth word 
BIT10N will be executed. 

Re-writing the "2BIT-TEST" word using the CASE .. ENDCASE structure results in a 
qFORTH code which is more readable and thus easier to understand: 



2BIT-CASE 
CASE 

0 OF BITOOFF ENDOF 

1 OF BITOON ENDOF 

2 OF BITIOFF ENDOF 

BITION 

ENDCASE ; 



The CASE selectors are not limited to constants (e.g. high-score @). 



15 CONSTANT TILT 
: PIN-BALL 
CASE 

0 OF 

HIGH-SCORE @ OF 
TILT OF 

( ELSE ) 

ENDCASE ; 



( BALL-CODE -- ) 

FREE -BALL ENDOF 
REPLAY ENDOF 
GAME -OVER ENDOF 
UPDATE- SCORE 
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3.14.2 Loops, Branches 
and Labels 



3.14.2.1 Definite Loops The DO .. LOOP control structure is an example of a definite loop. The number of times 

the loop is executed by the MARC4 must be specified by the qFORTH programmer. 

Example: 

: DO -Example 

12 5 ( -- Ch 5 ) 

DO ( Ch 5 -- ) 

I 1 OUT ( Copy loop-index I onto TOS ) 

LOOP ( Write " 5 6 7 8 9 Ah Bh" to portl ) 



Here, the loop index I starts at the value 5 and is incremented until the value 12 is 
reached. This is an example where we have defined a definite looping range (from 5 to 
1 1) for the statements between the DO and the LOOP to be repeated. 

On each iteration of a DO loop, the LOOP operator will increment the loop index. It then 
compares the index to the loop's limit to determine whether the loop should terminate or 
continue. 

In addition to the FORTH-83 looping construct, the MARC4 has special hardware sup- 
port for the qFORTH #DO .. #LOOP. 

As a result of this, the #DO..#LOOP is the most code and speed efficient definite loop 
and is recommended for most loop constructs. 

Example: 

5 #DO HELLO -WORLD #LOOP 

In this example, the loop control variable is set to 5, then decremented at the end of 
each iteration until 0. Hence, 5 #DO .. #LOOP will loop 5 times. 

#LOOPS may also be nested (to any depth). The outer loop control variable is called J 
when used inside the inner loop. 

Example: 

: NESTED-LOOPS 

7 #DO \ OUTER LOOP 

5 #DO \ INNER LOOP 

I J + 
PortO OUT 
#LOOP 
#LOOP 



Care should be taken when using loops to compute multi-nibble arithmetic (e.g. 16-bit 
shift right). This is because the standard FORTH-83 definite loops change the Carry flag 
after each iteration of the loop. In such cases, the #DO .. #LOOP is recommended since 
the Carry flag is not affected. 
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3.14.2.2 Indefinite Loops 



?D0 .. 


( limit start — ) 


IF start = limit THEN skip the loop 


7LEAVE 


( ~ ) 


exit loop if the Branch flag is true 


LOOP, 


( ) 


increment loop-index by 1 


DO .. 


( limit start — ) 


Init iterative DO. .LOOP 


-7LEAVE 


( -- ) 


if Branch flag is false, then exit loop 


LOOP 




increment loop-index by 1 


?DO .. 


( limit start -- ) 


IF start = limit THEN skip the loop 


LOOP 


(--) 




DO.. 


( limit start - ) 


Iterative loop with steps by <n> 


+LOOP 


(n~) 


increment loop-index by n 


#DO .. 


(n-) 


Execute #LOOP block n-times 


#LOOP 


(--) 


decrement loop-index until n = 0 



BEGIN indicates the start of an indefinite loop-control structure. The sequence of words 
which are to be performed by the MARC4 processor will be repeated until a conditional 
repeat construct (such as UNTIL or WHILE .. REPEAT) is found. Write a counter value 
from 3 to 9 to Port 1 , then finish the loop. 

Example: 

: UNT I L - Examp 1 e 
3 BEGIN 

DUP Portl OUT 
1 + 

DUP 9 > 
UNTIL 
DROP 



( Write the current value to Port 1 ) 
( Increment the TOS value 3 . . 9 ) 
( Duplicate the current value . . ) 
( the comparison will DROP it ) 
( skip counter value from stack ) 



The encapsulated BEGIN .. UNTIL loop block is then executed until the Branch flag is 
set (TRUE). The Branch flag is set when the desired condition (TOS > 9) is met. 

The second conditional loop control structure BEGIN .. WHILE .. REPEAT repeats a 
sequence of qFORTH words as long as a condition (computed between BEGIN and 
WHILE) is still being met. 

qFORTH also provides an infinite loop sequence, the BEGIN .. AGAIN which can only 
be escaped by EXIT, -7LEAVE or 7LEAVE. 
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Example: 

: BinBCD 



Fh <ROT 

BEGIN 
OVER 

WHILE 

10 M- 
ROT 1- 

REPEAT 

DUP 10 

IF 

10 

THEN 

NIP SWAP 



0<> 



<ROT 



ROT 1- 



NOT 



\ Converts binary to 2 digit BCD 
( d [<99] - Dhi Dlo ) 
\ 1 ' s comp of ' 0 ' 



\ High order is zero 



\ Count 10th 



<ROT 



SWAP 



Table 3-15. Indefinite Loops 



qFORTH - Indefinite Loops 


BEGIN <Condition> 
WHILE ... REPEAT 


Condition tested at start of loop 


BEGIN ...<Condition> UNTIL 


Condition tested at end of loop 


BEGIN ... AGAIN 


Unconditional loop 



3.14.3 Branches and While not recommended in normal programming, branches and labels have been 

Labels included in qFORTH for completeness. 

Labels have the following format: 

<Label>: <instruction> | <Word> 

Note: There is no space allowed between the label and the colon. 

Example: 

My_Labll : 

Only conditional branches are allowed in qFORTH, i.e., the branch will be taken if the 
Branch flag is set. 

If unconditional branches are required, then care must be taken to set the Branch flag 
before branching. 

Example: 

SET_BCF BRA My_Labll 

Note: The scope of labels is only within a colon definition. It is not possible to branch outside a 
colon definition. 
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Example: 

VARIABLE SINS 
VARIABLE TEMPERATURE 
: WAS -BAD? 

SINS @ 3 >= 



: NEXT-LIFE 

WAS -BAD? BRA HELL 
HEAVEN: TRA-LA-LA NOP 

SET_BCF BRA HEAVEN 
HELL: TEMPERATURE 1+ ! WORK 

SET_BCF BRA HELL 



The 'NEXT-LIFE' word can also be written with high-level constructs as: 

: NEXT-LIFE 

WAS -BAD? TOG_BF 
IF 

BEGIN 

TRA-LA-LA NOP \ HEAVEN 

AGAIN 
ELSE 
BEGIN 

Temperature 1+ ! WORK \ HELL 
AGAIN 
THEN 



3.14.4 Arrays and Look-up 
Tables 



3.14.4.1 Array Indexing 



3.14.4.2 Initializing and 
Erasing an Array 



INDEX is a predefined qFORTH word used to access array locations. The compiler 
translates INDEX into a run-time code definition, specific for the type of array being used 
(2ARRAY, LARRAY, etc.) 

By using the qFORTH word ERASE, it is possible to erase an array's content to be filled 
with zeros. 
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3.14.4.3 Array Filling A third way to initialize an array is using the word FILL. FILL requires that the beginning 

address of the array and the size of the array are placed onto the stack, followed by the 
value to be filled. 

: FillArray ( count n addr - ) 

Y! DUP [Y] ! ( count n addr - count n ) 

SWAP 1- ( count n -- n count -1 ) 

#DO DUP [+Y] ! 

#LOOP 

DROP 



3.14.4.4 Looping in an Array The qFORTH words contained between the DO and LOOP words are repeated 

between the start element and the limit element. The element first deposited onto the 
stack will be decremented following the store instruction. 

3.14.4.5 Moving Arrays The words MOVE and MOVE> copy a specified number of digits from one address to 

another within the RAM. The difference between the two instructions is that MOVE cop- 
ies the specified number of digits starting from the lowest address, while MOVE> starts 
from the highest address. 



C-MOVE ( n Source Dest -- ) 

Y! X! 
[X]@ [Y] ! 
BEGIN 

1- TOG_BF 
WHILE 

[+X] @ [+Y] ! 
REPEAT 
DROP 



3.14.4.6 Comparing Arrays The word "?Arrays=" compares two array fields, starting at the last field element in 

desending addresses. The maximum length permitted is 16 elements. The result, if the 
arrays are equal or not, is stored in the Branch flag. 



?Arrays= (n Arrayl [n] Array2 [n] -- [BF=1, if equal]) 

X! Y! 0 SWAP 

#DO 

[X-]@ [Y-]@ - OR 

#LOOP 
0 = 
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Another way of implementing the array-comparison function is to use the BEGIN .. 
UNTIL loop as shown below. 

: ?Arrays= (n Arrayl [n] Array2 [n] - [BF=1, if equal]) 
X! Y! 

BEGIN ( n is decremented in loop ) 

[Y-]@ [X-]@ 
<> ? LEAVE 
1- 

UNTIL 

DROP TOG_BF 



Array examples are included in section 4 "qFORTH Language Dictionary". 

3.14.5 Look-up Tables Look-up tables are implemented in most microprocessors to hold data which can be 

easily accessed by means of an offset. qFORTH supports tables with the instructions: 
ROMCONST, ROMByte®, DTABLE® and TABLE ;; . 

These instructions are described in section 4 "qFORTH Language Dictionary". The 
basic principle of MARC4 tables is that the data to be referenced is placed into contigu- 
ous ROM memory during compile time when defined as a ROMCONST. The 
ROMByte® word fetches an 8-bit constant from ROM defined by the 12-bit ROM 
address which is on the top of the Expression Stack. The DTABLE® word permits the 
user to access a particular 8-bit constant from the array via the array's address value 
and the 4-bit offset. 

In the program file "INCDATE.INC", found on the applications disk, the days of the 
month are placed into a look-up table called "DaysOfMonth". The month is used to 
access the table in order to return the number of days in the month. 

3.14.6 TICK and EXECUTE The word ' (pronounced TICK, represented in FORTH by the apostrophe symbol) 

locates a word definition in memory and returns its ROM address. 

EXECUTE takes the ROM address (located on the Expression Stack) of a colon defini- 
tion and executes the word. TICK is useful for performing a vectored execution where a 
word definition is executed indirectly, this can be performed by placing the address of a 
definition into a variable. The content of the variable is then EXECUTEd as desired. This 
gives the user increased flexibility as complicated pointer manipulations can now be 
performed. 
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Example: 

CODE BCD_+1! 

[Y] @ 1 + DAA [Y-] ! 
END -CODE 
: Inc_Hrs 

Time [Hrs_l] Y! BCD_+1 ! 

IF 

Time [Hrs_10] 1+! 
THEN 

Time [Hrs_10] 2@ 2 4 D= 
IF 

0 0 Time [Hrs_10] 2! 
THEN 



\ <Y> = A Digit <Y-1> 

\ Incr. BCD digit in RAM 



\ x9:59 -> x+1 0:00 

\ 0 -> 1 or 1 -> 2 

\ 24:00:00 ? 

\ 23:59 -> 00.00 

\ It's midnight 



Inc_Hour 

LAP_Timer [Hours] 1+! 



\ Inc Hours binary by 1 
\ Wrap around at 16:00.00 



Inc_Min 
BCD_+1 ! 
IF 

[Y] @ 1+ 6 CMP_EQ [Y] ! 
IF 

0 [Y-] ! 

Hours_Inc 3@ EXECUTE 
[ E 0 R 0 ] 
THEN 
THEN 



\ <y> = ~Digit [Min_l] 

\ 18:29 -> 18:30 

\ On overflow . . 

\ 18:59 -> 19:00 

\ Reset Min_10 

\ Computed Hrs_Inc ' 



Inc_Secs 
BCD_+1 ! 
IF 

[Y] @ 1+ 6 CMP_EQ [Y] ! 
IF 

0 [Y-] ! 
Inc_Min 

THEN 
THEN 



\ <Y> = ~Digit [Sec_l] 

\ Increment seconds 

\ 8:25:19 -> 8:25:20 

\ 8:30:59 -> 8:31:00 

\ Reset Sec_10 

\ Incr. Minutes 
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Inc_l/100s 
BCD_+1 ! 
IF 

BCD_+1 ! 
IF 

Inc_Secs 

THEN 
THEN 



\ Increment 10_ms 

\ 25.19.94 -> 25.19.95 

\ Incr. 100_ms 

\ 30.49.99 -> 30.50.00 

\ Incr. seconds . . 



IncTime 

' Inc_Hrs Hours_Inc [2] 3 
Time [Sec_l] Y! Inc_Secs 



\ Incr. T.O.D. 

\ Note use of Tick 

\ Increment seconds 



Inc_10ms \ Incr. LAP timer 

1 Inc_Hour Hours_Inc [2] 3! \ Note use of TICK 
LAP_Timer [10_ms] Y! 

Inc_l/100s \ Increment 1/100 sec 



\ Excerpts of program 'TEST_05' which includes TICKTIME 



9 CONSTANT Seed 

6 ARRAY Time 

7 ARRAY LAP_Timer 
3 ARRAY Hours_Inc 
2 ARRAY C_INT6 

VARIABLE RandomUpdate 
VARIABLE LAP_Mode 
VARIABLE TimeCount 



\ Random display update 

\ Current Time Of Day 

\ Stop Watch time 

\ Dest. of computed GOTO 

\ INT6 counter 

\ LAP_Timer or T.O.D. display 

\ Count RTC interrupts 



$ INCLUDE LCD_3tol 
$ INCLUDE TickTime 
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Stopwatch 
C_INT6 [1] D-l! 
IF 

2 6 C_INT6 2 ! 

Inc_10ms RandomUpdate 1- ! 
IF 

Seed RandomUpdate ! 
LAP_Timer [1] Show6Digits 

THEN 
THEN 



INT5 \ Real-Time Clock Interrupt 

every 1 / 2 s 

1 TimeCount TOGGLE 

IF DI IncTime EI THEN \ Be on the save side 



INT 6 

LAP_Mode @ 0= 

IF Stopwatch THEN 



\Stop Watch Interrupt 
every 244.1 usee 



$RESET 

>SP SO >RP FCh \ Init stack pointers first 

Vars_Init ( etc. ) ; \ Setup arrays and prescaler 
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Compiler directives allow the programmer to have direct manual control of the genera- 
tion and placement of program code and RAM variables. The qFORTH compiler will 
automatically generate an efficient code, so it is not necessary or recommended to man- 
ually optimize the application program at the beginning of the project. However, when 
the first version of the application is completed, the following compiler directives can be 
used to "fine tune" the program. 

A complete list of all compiler directives may be found in the documentation shipped 
with the qFORTH2 compiler release disk. 

3.15.1 Controlling ROM By forcing a zero page placement of the most commonly used words, a single byte short 
Placement call will be used to access the word, hence saving a byte per call. 

Examples: 

: Called-a-lot SWAP DUP [ Z ] ; 

\ Place anywhere in zero page 



3.15 Making the Best 
Use of Compiler 
Directives 



Once-in-a-blue-moon Init-RAM [ N ] ; 

\ Don't place in zero Page 



: Very- Small -Word 3>R DUP 3R@ ; AT 23h 

\ Place in 5 byte hole between zero page words 

3.15.2 Macro Definitions, If fast execution is required, critical words may be invoked as macros and expanded "in- 
EXIT and ;; line". In general, macros are identical in syntax to word definitions, except the colon and 

semicolon which are replaced by CODE .. END-CODE. 

Clearly "CODE" definitions have no implied EXIT (or subroutine return) on termination. 
Occasionally, a colon definition does not require an EXIT on termination. If this is the 
case, the statement is used instead of the 

Examples: 



07 2 CONSTANT Duff-Value 



nCODE Must-be-fast 



X! [X]@ 



Correlate -Temperature 

Read-Temperature 

2 DUP Duff-Value D= 

2 DROP 

EXIT 

THEN 

Do -Correlation 



1+ [X-] ! 
END -CODE 



( -- Th Tl ) 

IF \ Make a quick exit if 

\ duff data read in 

\ Note use of EXIT 



( Th Tl 



) 



HALT BEGIN AGAIN ; ; 



\ Since this loop 

\ never terminates, 

\ then we can save the EXIT 
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3.15.3 Controlling Stack 
Side Effects 



The qFORTH compiler attempts to calculate the stack effects of each word. Sometimes, 
this is not possible, hence the two directives [ E <number> R <number> ] allow the pro- 
grammer to manually set stack effects of the Expression and the Return Stack. 



Examples: 

: I-know-what-I ' m-doing 
: Get_Numbers 



Flag 
IF 

12 3 
ELSE 
12 3 
THEN 



@ 5 = 



[ E 4 ] 



BEGIN DUP 1- UNTIL [ E 0 ] ; 

\ Depending on the value of Flag 

\ the IF. .ELSE. .THEN block will have 

\ a stack effect of +4 or +3 . 



3.15.4 SINCLUDE Directive It is common programming practice to split a large program into a number of smaller 

modules, i.e, one file per module. qFORTH allows the programmer to do this with the 
SINCLUDE <filename[.INC]> directive. This directs the compiler to temporarily take the 
input source from another file. 

Include-files may be nested up to a maximum of four levels. 
Example: 

$ INCLUDE Lcd-Words \ include the LCD "tool box" 

: Update_LCD 

Colon-State @ Blink-Colon? 



3.15.5 Conditional Conditional compilation enables the programmer to control which parts of the program 

Compilation are to be compiled. A typical program under development for example has an extra 

code to aid debugging. This code is removed on the final version. By using a conditional 
compilation, the programmer can keep all the debugging information in the source, but 
generate the code only for the application simply by commenting out the $DEFINE 
DEBUG directive. 



Examples: 

$ DEFINE Debug 
: INT2 



\ IF this directive is commented out 
\ THEN no debugging code is generated 



$ IFDEF Debug 

CPU-Status Port6 OUT 
$ENDIF 

Process-Int2 
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$DEFINE Emulation \ Use EVA prescaler 

$IFDEF Emulation 

Eh CONSTANT Prescaler_2 

Ch CONSTANT 4_KHz 
$ELSE 

Fh CONSTANT Prescaler_2 
Dh CONSTANT 4_KHz 
$ENDIF 



$IFDEF Emulation 

: INT4 process ; 

$ELSE 

: INT6 process ; 

$ENDIF 



3.15.6 Controlling XY The X/Y optimize qualifiers of the qFORTH compiler help to control the depth of desired 

Register optimization steps. 

Optimizations . XYLOAD 

the sequence LIT_p .. LIT_q X! is optimized to: >X $pq 

• XY@! 

the sequence >X $pq [X]! is optimized to: [>X]! $pq 

• XYTRACE 

reloading the X or Y register (i.e., sequences of >X $pq will be replaced by [+X]@ or 
[Y-]! operations whenever possible. 

The qFORTH compiler keeps track of which variable is cached in the X and Y registers 
inside a colon definition. 

Example: 

The variables "On_Time" and "SwitchNr" are stored in consecutive RAM locations. 



Table 3-16. 



qFORTH Source 


Intermediate 
Code 


XYLOAD, XY@! 
Optimized 


Final Code after 
XYTRACE 


On_Time @ 


LIT_3 LIT_4 


[>X]@ $On_Time 


[>X]@ $On_Time 


SwitchNr +! 


X! [X]@ 


[>Y]@ $SwitchNr 


[+X]@ 




LIT_3 LIT_5 


ADD 


ADD 


Y! [Y]@ 


[Y]! 


[X]! 


ADD 






[Y]! 


10 Bytes 


6 Bytes 


5 Bytes 
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3.16 Recommended 
Naming 
Conventions 



3.16.1 How to Pronounce 
the Symbols 



I 


store 


[] 


square brackets 


<& 


fetch 




quote 


# 


sharp or "number" 




as prefix: Tick; as suffix: prime 


$ 


dollar 




tilde 


0/ 

/O 


percent 


1 


bar 


A 


caret 


\ 


backslash 


& 


ampersand 


/ 


slash 


* 


star 


< 


less-than; left dart 


0 


left paren and right paren ; paren 


> 


greater-than; right dart 




dash; not 


? 


question or "query" 


+ 


plus 




comma 




equals 




dot 


{} 


faces or "curly brackets" 







Form 



Example 



Meaning 



Arithmetic 

1name 

2name 

+name 

*name 

Data structures 

names 

#name 

name# 

( n) name 

+name 

name+ 

/name 
>name 

Direction, 

conversion 

name< 

name> 

<name 

>name 

name>name 

\name 

/name 



1 + 

2DUP 

+DRAW 

*DRAW 



EMPLOYEES 

#EMPLOYEES 

EMPLOYEE* 

EMPLOYEE [13] 

+EMPLOYEE 

DATE+ 

/SIDE 
>IN 



SLIDE< 

MOVE> 

<PORT4 

>PORT0 

FEET>METERS 

\LINE 

/LINE 



integer 1 (4-bit) 
integer 2 (8-bit) 

takes relative input parameters 
takes scaled input parameters 



table or array 

total number of elements 

current item number (variable) 

sets current item 

advance to next element 

size of offset to item from beginning of 

structure 

size of (elements "per") 
index pointer 



backwards 
forwards 
from 
to 

convert to 
downward 
upward 
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Logic, control 



name? SHORT? return Boolean value 

-name? -SHORT? returns reversed Boolean 

?name ?DUP ( maybe DUP) operates conditionally 

+name +CLOCK enable 

name BLINKING or, absence of symbol 

-name -CLOCK disable 
-BLINKING 

Memory 

©name ©CURSOR save value of 

Iname ICURSOR restore value of 

name! SECONDS! store into 

name© INDEX© fetch from 

' name ' INC-MINUTE address of name 



Numeric types 
Dname 

Mname 
Tname 
Qname 



D+ 

M* 
T* 
Q* 



2 cell size, 2's complement integer 
encoding 

mixed 4 and 8-bit operator 

3 cell size 

4 cell size 



These naming conventions are based on a proposal given by Leo Brodie in his book 
"Thinking FORTH". 
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3.17 Literature List 



3.17.1 Recommended "Starting Forth" is highly recommended as a good general introduction to FORTH, 

Literature especially chapters 1 to 6. 

"Starting FORTH" is now also available in German, French, Dutch, Japanese and 
Chinese. 

"Thinking FORTH" is the follow-on book to "Starting FORTH" and discusses more 
advanced topics, such as system-level programming. 

"Complete FORTH" has been acknowledged as the definitive FORTH text book. 



Title: 


"Starting FORTH" (2nd edition) 


Author: 


Leo Brodie 


Publisher: 


Prentice Hall, 1987 


ISBN: 


0-13-843079-9 


Title: 


"Programmieren in FORTH" (German Version) 


Author: 


Leo Brodie 


Publisher: 


Hanser, 1984 


ISBN: 


3-446-14070-0 


Title: 


"Thinking FORTH" 


Author: 


Leo Brodie 


Publisher: 


Prentice Hall, 1984 


ISBN: 


0-13-917568-7 


Title: 


"Complete FORTH" 


Author: 


Winfield 


Publisher: 


Sigma Technical Press, 1983 



3.17.2 Literature of General The following list shows the spectrum of FORTH literature. This literature is of back- 
Interest ground interest ONLY and may contain information which is not completely relevant for 
programming in qFORTH on the MARC4. 



Title: "Mastering FORTH" 

Author: Leo Brodie 

Publisher: Brady Publishing, 1989 

ISBN: 0-13-559957-1 

Title: "Dr. Dobbs Tool-Box of FORTH Vol. II", 

Publisher: M&T Books, 1987 

ISBN: 0-934375-41-0 

Title: "FORTH" (Byte Magazine) 

Author: L. Topin 

Publisher: McGraw Hill, 1985 
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Title: 


"The use of FORTH in process control" 




Proc. of the International 77 Mini-Micro Computer Conference, 




ucl level, 


Muinor s. 


ivioore ex riainer 


Publisher: 


1 PC and Technology Press, England, 1977 


Titlp- 

1 1 LIC 


"FORTH" A rrtct enwinn annrnsrh \n QrvftiflfSH'A npyplnnmpnt" 
i \j n i n ■ r\ uuoi oci v 1 1 1 y auui uaui i iu oui i vvcti c l/cvciul/i i ici i i 






Publisher: 


Wescon/Los Angeles, 1978 


i me. 


run i n s rone is i lymer rroyrarniTiiny 


Ai ithnr 

rAU ii \\J\ . 


Hirkq 

1 IIU r\ O 


Pi i h\ 1 i oh or ■ 


CltrULl Ul 1 IL-o ^IVlctyaZII IfcJj, IvIdlUll 1 C7 / C7 


Title: 


"FORTH a text and reference" 


Author: 


Kelly & Spier 


Publisher: 


Prentice Hall, 1986 


ISBN: 


0-13-326331-2 
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Section 4 

qFORTH Language Dictionary 



4.1 Preface This dictionary is written as a reference guide for programmers of the MARC4 microcon- 

troller family. 

The qFORTH DICTIONARY categorizes each qFORTH word and MARC4 assembler 
instruction according to its function (purpose), category, stack effects and changes to 
the stack(s) by the instruction. The affected condition flags, X and Y register changes 
are also described in detail. The length of each instruction is specified by the number of 
bytes generated at the time of compilation. A short demonstration program for each 
instruction is also included. 

The qFORTH language is described in section 3 "Programming in qFORTH" which 
includes a language tutorial and learner's guide. First-time programmers of qFORTH are 
urged to read this chapter before consulting this guide. 

The associated effects and changes of the listed qFORTH word are described in this 
reference guide. 

The entries are sorted in alphabetical order. You can find a reference in the index for 
unused MARC4 assembler mnemonics. 



Every entry in this dictionary is listed on a separate page. 

The page structure for every entry contains the topics in the following sections. 

This section gives a short explanation of each qFORTH vocabulary entry and explains 
its operational function. 

A classification of the qFORTH vocabulary entries is given. 

All entries in this dictionary are classified in the following categories (the same catego- 
ries are used in section 4.6 "MARC4 qFORTH Quick Reference Guide"): 

A: Usage-specific categories: 

Arithmetic ("+", "-" ... ), logical operations ("AND", "OR") and bit manipulations ("ROR" ...) 
on 4-bit or 8-bit values. 

Comparison operations on either single- or double-length values resulting in the Branch 
condition flag being set to determine the program flow (">", ">=", ... ). 



4.2 Introduction 

4.2.1 Purpose 

4.2.2 Category 

4.2.2.1 Arithmetic/Logical 

4.2.2.2 Comparisons 
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4.2.2.3 Control Structures 



4.2.2.4 Interrupt Handling 



4.2.2.5 Memory Operations 

4.2.2.6 Stack Operations 



4.2.2.7 Assembler 
Instructions 

4.2.2.8 qFORTH Colon 
Definitions 



4.2.2.9 qFORTH Macro 
Definitions 

4.2.2.10 Predefined Data 
Structures 



4.2.2.11 Compiler Directives 



4.2.3 Library 

Implementation 



Control structures are used for conditional branches such as 
IF ... ELSE ... THEN and loops (DO ... LOOP). 

The MARC4 instruction set allows the programmer to handle up to 8 hardware/software 
interrupts and to enable/disable all interrupts. Other qFORTH words permit the program- 
mer to determine the actually used depth or available free space on the Expression and 
Return Stack. 

Read, modify and store single-, double- or multiple-length values in memory (RAM). 

The sequence of the items and the number or the value of items held on the stack may 
be modified by stack operations. Stack operations may be of single-, double- or triple 
(12-bit)-length ("SWAP", ... ). 

B: Language-specific categories: 

qFORTH programs may contain MARC4 native code instructions; all qFORTH words 
consist of assembler and/or qFORTH colon definitions and/or qFORTH macros. 

All qFORTH colon definitions begin with a ":" and end with a They are processed like 
subroutines in other high-level languages; that means, that they are "called" with a short 
(1) or long CALL (2 bytes) at execution time. The ";" is translated to an EXIT instruction 
(return from subroutine). At execution time, the program counter is loaded with the call- 
ing address from the Return Stack. Colon definitions can be "called" from various 
program locations as opposed to qFORTH macros which are placed "in-line" by the 
compiler at each "calling" address. 



All qFORTH macros begin with a "CODE" and end with an "END-CODE" 
replaces the macro definition by an in-line code. 



The compiler 



Predefined data structures do not use any ROM-bytes (except ROM look-up tables). 
They are used for defining constants, variables or arrays in the RAM. With "AT", you can 
force the compiler to place a qFORTH word at a specific address in the ROM or a vari- 
able at a specific address in the RAM. 

Compiler directives are used to include other source files at compilation time, to define 
RAM or ROM sizes for the target device or to control the RAM or ROM placement (p.e. 
$INCLUDE, $RAMSIZE, $ROMSIZE). 

Most entries belong to a usage-specific and a language-specific category, i.e. "+" 
belongs to the category arithmetic/logical and to the category assembler instructions; 
"VARIABLE" belongs only to the category predefined data structures. 

For qFORTH words which are not MARC4 assembler instructions, the assembly level 
implementation is included in the description. Refer to the library items "CODE" / "END- 
CODE" and ":" / ";" for improved understanding of this representation. 

These items will help when simulating/emulating the generated code with the simula- 
tor/emulator or when optimizing your program for ROM length. 

The MARC4 native code is written in the dictionary for MARC4 assembler instructions. 

The assembler mnemonic "(S)BRA" means that the compiler tries to optimize all BRA 
mnemonics to SBRA (short branches * only one byte) if the option is switched on and 
optimization is possible (page boundaries can not be crossed by the SBRA, but only by 
the BRA). 
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4.2.4 Stack Effect 

4.2.5 Stack Changes 

4.2.6 Flags 

4.2.7 X Y Registers 



4.2.8 Bytes Used 

4.2.9 See Also 

4.2.10 Example 



This category describes the effects on the Expression and Return Stack when executing 
the described instruction. See section 4.3 "Stack-related Conventions" to better under- 
stand the herein used syntax and semantics. 

These lines include the number of elements which will be popped from or pushed onto 
the stacks when executing the instruction. 

The "flags" part of each entry describes the flag effect of the instruction. 

In this part, the effect on the X and Y registers is described. This is only important if the 
X or Y registers are explicitly referenced. 

Note: The compiler optimizer changes the used code inside of colon definitions through the 
X/Y-register-tracking technique. 

Attention: The X register can be replaced in qFORTH macros by the Y register and vice 
versa (see the explanation of the optimizer in the qFORTH compiler user's guide). 

This part gives the number of bytes used in the MARC4 ROM by the qFORTH colon def- 
inition, the qFORTH macro or by the assembler instruction. 

Note: The optimizer of the compiler may shorten the actual program module. 

This section includes similar qFORTH words or words of the same category. The "%" 
symbol in this field signifies that there are no similar words for this entry. 

An example for using the described qFORTH word is given in this section. All examples 
are tested and may be demonstrated with the MARC4 software development system. 



4.3 Stack-related 
Conventions 



4.3.1 Expression Stack 



4.3.2 Return Stack 



4.3.3 X/Y-registers 



4.3.4 Stack Notation 



The Expression Stack contains the program parameters. This stack is referred to as 
either the "EXP Stack" or just "EXP", "data stack" or just "stack". 4-, 8- and 12-bit data 
elements are placed onto the stack with the least significant nibble on top. 

The Return Stack contains the subroutine return addresses as well as the loop indices 
and is also used to temporarily unload parameters from the Expression Stack. This 
stack is referred to as either the "RET stack" or just "RET". 

The two general-purpose X and Y 8-bit registers permit direct and indirect access (with 
additional pre-increment or post-decrement addressing modes) to all RAM cells. 

addr 8-bit memory address 

n 4-bit value (nibble, single length) 

byte 8-bit value (represented as a double nibble) 

d 8-bit unsigned integer (double length) 

h m I "higher middle lower" nibble of a 12-bit value 

t 12-bit memory/stack operation (triple length) 

flags the flags of the Condition Code Register 
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The stack effects shown in the dictionary represent the stack content, separated by two 
dashes ( -- ), before and after execution of the instruction. 

The Top of Stack (TOS) is always shown on the right. As an example, the SWAP and 
DUP instructions have the following Expression Stack effects: 

before: after the operation. 

I I 
SWAP EXP : ( n2 n1 -- n1 n2 ) 
DUP EXP : ( n1 -- n1 n1 ) 

TOS (top of stack) 



A similar representation specifying the stack effect of an instruction shows the stack 
contents after execution. 



Expression Stack: 



1 2 

Push two 
constants 



TOS 



SWAP 

Swap top 
two elements 



TOS 



DUP 

Duplicate 
top elements 



1 TOS 
1 

2 



Return Stack notation: 

A Return Stack entry contains a maximum of 3 nibbles on each level (normally a 12-bit 
ROM address). 

If (e.g. in a DO. .LOOP) only 2 nibbles of 3 possible nibbles are required there is "u" for 
"undefined" or "don't care" used in the notation: 



3 1 DO ( RET: -- u I limit | index ) or ( RET: -- u I 3 1 1 ) 
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4.4 Flags and 

Condition Code 
Register 



There are three flags which interact with qFORTH instructions. Together with a fourth 
flag, which is reserved for Atmel, they are accessible via the 4-bit Condition Code Regis- 
ter - "CCR". 

A binary value 1 indicates that the corresponding flag has been set. A binary value 0 
indicates a cleared flag. 

The order of the flags in the CCR is used in text as follows: 
Carry C bit 3 CARRY flag (MSB) 

% % bit 2 (reserved) 

Branch B bit 1 BRANCH flag 

Interrupt enable I bit 0 LENABLE flag (LSB) 



4.5 MARC4 Memory 
Addressing 
Model 



4.5.1 Memory Operations 



4-bit variable 
8-bit variable 
12-bit variable 



address points to 
address points to 
address points to 



^RAM 



nh 



nl 



nh 



nm 



nh = most significant nibble 
nl = least significant nibble 

See the entries 2/VARIABLE, 2/L/ARRAY and 2/3@ for further information. 
The following example shows, how to handle an 8-bit variable: 



1 CONSTANT njow 
2VARIABLE KeyPressTime 



( constant and variable declaration 
( 8-bit variable 



) 



nl 



: Example 

0 0 KeyPressTime 2! 
KeyPressTime 2 @ 1 M+ 

IF DROP 1 THEN 
KeyPressTime 2! 



( initialize this variable 

( increment by 1 the 8-bit variable 

( the lower nibble is on top of 

( reset to 01 h on overflow 

( store the new 8-bit value back 
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4.6 The qFORTH 
Language - 
Quick Reference 
Guide 



4.6.1 Arithmetic/Logical 



4.6.2 Comparisons 



+C 

1 + 

1- 

2* 

21 

D+ 

D- 

D2/ 

D2* 

M+ 

M- 

AND 

OR 

ROL 

ROR 

SHL 

SHR 

NEGATE 

DNEGATE 

NOT 

XOR 

> 

< 

>= 
<= 
<> 

0<> 



EXP 
EXP 
EXP 

EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 
EXP 



n1 n2 - n1-n2 ) 
n1 n2 - n1+n2 ) 
n1 n2 - n1+/n+/C 



n1 n2 - n1+n2+C ) 

n - n+1 ) 

n - n-1 ) 

n - n*2 ) 

n - n DIV 2 ) 

d1 d2-d1+d2) 

d1 d2 - d1-d2 ) 

d - d/2 ) 

d - d*2 ) 

d1 n - d2 ) 

d1 n - d2 ) 

n1 n2 - n1 A n2 ) 

n1 n2 - n1 v n2 ) 
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Subtract the top two nibbles 

Add up the two top 4-bit values 

1's complement subtract with 
borrow 

Add with Carry top two values 
Increment the top value by 1 
Decrement the top value by 1 
Multiply the top value by 2 
Divide the 4-bit top value by 2 
Add the top two 8-bit values 
Subtract the top two 8-bit values 
Divide the top 8-bit value by 2 
Multiply the top 8-bit value by 2 
Add a 4-bit to an 8-bit value 
Subtract 4-bit from an 8-bit value 
Bit-wise AND of top two values 
Bit-wise OR the top two values 
Rotate TOS left through Carry 
Rotate TOS right through Carry 
Shift TOS value left into Carry 
Shift TOS value right into Carry 
2's complement the TOS value 
2's complement top 8-bit value 
1 's complement of the top value 
Bit-wise Ex-OR the top 2 values 
If n1>n2, then Branch flag set 
If n1<n2, then Branch flag set 
If n1>=n2, then Branch flag set 
If n1<=n2, then Branch flag set 
If n1on2, then Branch flag set 
If n1=n2, then Branch flag set 
If n <>0, then Branch flag set 
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4.6.3 



Control Structures 



0= 


EXP 


(n~) 


If n = 0, then Branch flag set 


D> 


EXP 


( d1 d2 - ) 


If d1>d2, then Branch flag set 


D< 


EXP 


( d1 d2 - ) 


If d1<d2, then Branch flag set 


D>= 


EXP 


( d1 d2 - ) 


If d1>=d2, then Branch flag set 


D<= 


EXP 


( d1 d2 - ) 


If d1<=d2, then Branch flag set 


D= 


EXP 


( d1 d2 - ) 


If d1=d2, then Branch flag set 


Do 


EXP 


( d1 d2 - ) 


If d1od2, then Branch flag set 


DOo 


EXP 


(d-) 


If d <>0, then Branch flag set 


D0= 


EXP 


(d~) 


If d =0, then Branch flag set 


DM AX 


EXP 


( d1 d2 - dMax ) 


8-bit maximum value of d1 , d2 


DMIN 


EXP 


(d1 d2 -dMin) 


8-bit minimum value of d1 , d2 


MAX 


EXP 


( n1 n2 - nMax ) 


4-bit maximum value of n1 , n2 


MIN 


EXP 


( n1 n2 - nMin ) 


4-bit minimum value of n1 , n2 


AlaAIN 


run 

bAr 


(-) 


Ends an infinite loop BEGIN .. 
AGAIN 


DbuIN 


r v n 
bAr 


(-) 


BEGIN of most control 
structures 


UAbb 


EZVD 

bAr 


( n — n ) 


begin ot uaoc .. cNUOAoc 
block 


uu 


EZVD 

bAr 
RET 


( limit start — ) 

( - u | limit start ) 


Initializes an iterative DO..LOOI 


ELSE 


EXP 


(-) 


Executed when IF condition is 
false 


ENDCASE 


EXP 


(n~) 


End of CASE. .ENDCASE block 


ENDOF 


EXP 


( n - n ) 


End of <n> OF .. ENDOF block 


even itc 
cacLU 1 b 


EZVD 

bAr 


( KUiviAaor — ) 


Execute word located at 
ROMAddr 


rv|T 
bAl 1 


DEZX 

Kb 1 


( KUlviAaar — ) 


Unstructured EXIT from 
":"-definition 


IF 


EXP 


(-) 


Conditional IF .. ELSE .. THEN 
block 


LOOP 


EXP 


(-) 


Repeat LOOP, if index+1< limit 


<n> OF 


EXP 


(cn-) 


Execute CASE block, if n =c 


REPEAT 


EXP 




Unconditional branch to BEGIN 
of BEGIN .. WHILE REPEAT 


THEN 


EXP 


(-) 


Closes an IF statement 


UNTIL 


EXP 




Branch to BEGIN, if condition is 
false 


WHILE 


EXP 


(-) 


Execute WHILE .. REPEAT 



block, if condition is true 
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4.6.4 Stack Operations 



+LOOP 


EXP 
RET 


; n - ) 

; u limit l-u limit l+n ) 


#D0 


EXP 


n - ) RET ( - u | u | n ) 


ffLUUr 


rvn 

bXr 


i - ) 




RET 


; u u i-u u 1-1 ) 


?D0 


EXP 


Limit Start - ) 


7LEAVE 


EXP 


;-) 


-7LEAVE 


EXP| 


-) 


0 .. Fh, 


EXP 


;-n) 


0 .. 15 


EXP 


-n) 


' <name> 


EXP 


[ - ROMAddr ) 


<ROT 


EXP| 


n1 n2 n - n n1 n2) 


>R 


EXP 


[ n - ) RET ( - u | u | n ) 


?DUP 


EXP| 


n - n n ) 


DEPTH 


EXP 


;-n) 


DROP 


EXP | 


' n -) 


DUP 


EXP 


[ n - n n ) 


1 

1 


tAr 


1 \ OCT /ill ill 1 ill ill 

— 1 ) nt 1 ( U | U| 1 — U| U| 


J 


EXP 


-j) 




RET 


u u J u u l-u u J 


NIP 


EXP | 


n1 n2 — n2 ) 


OVER 


EXP 


; n1 n2 - n1 n2 n1 ) 




rvn 

bAr 


x - n[x] ) 


RFREE 


EXP 


-n) 


n> 


CYD 


K ■■ n ) nt i ( u i u i n ■■ ) 


R@ 


EXP 


;-n) 




RET 


[u| u n~u| u n) 



Repeat LOOP, if l+n < limit 

Execute the #DO .. #LOOP 
block n times 

Decrement loop index by 1 
down to zero 

if start=limit, skip LOOP block 
Exit any loop, if condition is true 
Exit any loop, if condition is false 

Push 4-bit literal on Exp. Stack 
Places ROM address of colon 
definition 

<name> on Exp. Stack 

Move top value to 3rd stack 
position 

Move top value onto the Return 
Stack 

Duplicate top value, if n <>0 

Get current Expression Stack 
depth 

Remove the top 4-bit value 

Duplicate the top 4-bit value 

Copy loop index I from Return to 

Expression Stack 

Fetch index value of outer loop 

[2nd Return Stack level 
il I ) entry] 

Drop second to top 4-bit value 

Copy 2nd over top 4-bit value 

Copy the x th value from the 

Expression Stack onto TOS 

Get # of unused Return Stack 
entries 

Move top 4-bits from return to 
Expression Stack 
Copy top 4-bits from return to 
Expression Stack 
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4.6.5 Memory Operations 



ROLL 


EXP 


(n~) 


Move n th value within stack to 
top 


ROT 


EXP 


( n1 n2 n - n2 n n1) 


Move 3rd stack value to top pos. 


QWAP 

O VV Mr 


FXP 


I 1 1 1 1 1£. 1 \C III 1 


Pyphannci tnn t\A/n \/qIijpc nn 

L^AL/l leu IUc LUU LVVU VCllUtJo UN 

stack 


TUCK 


EXP 


( n1 n2 - n2 n1 n2 ) 


Duplicate top value, move under 

co n nnH itom 
ocOUl IU ILfcJI 1 1 


2iR 


EXP 
RET 


1 1 1 1 1 1 1 

( - u | n2 | n1 ) 


Mn\/p ton t\A/n x/pIiipq from 

IVIU VC lUp LVVU VulUuo MUIM 

Expression to Return Stack 


2DR0P 


EXP 


( n1 n2 - ) 


Drop top 2 values from the stack 


2DUP 


EXP 


( d - d d ) 


Duplicate top 8-bit value 


2NIP 


EXP 


( d1 d2 - d2 ) 


Drop 2nd 8-bit value from stack 


20VER 


EXP 


( d1 d2 - d1 d2 d1 ) 


Copy 2nd 8-bit value over top 
value 




FXP 


l ri1 ri9 ri — ri ri1 t\V\ 
\ u i u& u u u i vi^^ 


IVIUVtJ LUU O UIL VctlUt! LU Ol U UUo. 


2R> 


EXP 

RFT 
n i i 


( - n1 n2 ) 

I U | 1 l£i | III f 


Move top 8-bits from Return to 
Expression Stack 


£. n 


FXP 

LAr 

RET 


i iii ii^ i 

( u n2 n1 - u I n2 n1) 


Pnnw tnn ft-hitc frnm rpti irn tn 

vUUy IUU O Ullo IIUIII IcUUIII LU 

Expression Stack 


2R0T 


EXP 


(d1 d2d- d2dd1) 


Move 3rd 8-bit value to top value 


2SWAP 


EXP 


( d1 d2 - d2 d1 ) 


Exchange top two 8-bit values 


L 1 UVI\ 


FXP 

LAr 


( rl1 ri9 — rl9 rl1 rl9 ^ 


Ti ifk' ton ft-hitc i inrlor Or\r\ h\/tp 

1 UOr\ IUU O Ullo Ul lUul ill IU UyLC 


3>R 


EXP 

RFT 
nL i 


( n1 n2 n3 - ) 

/ n*? n9 n1 ^ 

l 1 1 0 | 1 l£. | 1 1 1 1 


Move top 3 nibbles from the 

F- vnrpccinn r\ntr\ thp Rptiirn 

LA|JI troolUI 1 UIILU LI It; nCLUI 1 1 

Stack 


3DR0P 


EXP 


( n1 n2 n3 - ) 


Remove top 3 nibbles from 
stack 


ouur 


FXP 

LAr 


■ t -- t M 


L^UUMUcUt? LUU I c. UIL VdlUC 


3R> 


EXP 
RET 


l r>1 n2 n"? ^ 

( n3ln2ln1 -) 


Mn\/p ton *3 nihhlpQ frnm Rptiirn 

to the Expression Stack 


3R@ 


EXP 


( - n1 n2 n3 ) 


Copy 3 nibbles (1 entry) from the 




RET 


( n3 n2 n1 - n3 n2 n1 ) 


Return to the Expression Stack 


I 


EXP 


( n addr - ) 


Store a 4-bit value in RAM 


@ 


EXP 


( addr - n ) 


Fetch a 4-bit value from RAM 


+! 


EXP 


( n addr - ) 


Add 4-bit value to RAM contents 


1+! 


EXP 


( addr - ) 


Increment a 4-bit value in RAM 


1-! 


EXP 


( addr - ) 


Decrement a 4-bit value in RAM 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-9 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.6.6 



Predefined 
Structures 



2! 


EXP 


; d addr - ) 


2<S? 


run 

bXr 


addr — d ) 


D+! 


EXP 


[ d addr - ) 


D-! 


EXP 


d addr - ) 


DTABLE® 


EXP 


[ ROMAddr n - d ) 


DTOGGLE 


EXP 


d addr - ) 


ERASE 


EXP 


[ addr n - ) 


FILL 


EXP 


addr n n1 - ) 


MOVE 


EXP 


[ n from to ~ ) 


hum byte 


run 

bAr 


KUlviAaar — d ) 


TOGGLE 


EXP 


[ n addr - ) 


3! 


EXP 


' nh nm nl addr - ) 




caH 


[ addr — nh nm nl ) 


T+! 


EXP! 


' nh nm nl addr - ) 


T-! 


EXP 


[ nh nm nl addr - ) 


TD+! 


EXP| 


d addr - ) 


TD-! 


EXP ( 


; d addr - ) 


( ccccccc) 






\ ccccccc 






: <name> 


RET 


-) 




RET 


; ROMAddr - ) 


[hlHo 1 J 


bAr 


> -- o ) 


[LAST] 


EXP 


; - nld ) 


CODE 


EXP 


-) 


riin /-> f\ p* r~ 

bNU-OUUt 


bAr 


i - ) 


ARRAY 


EXP 


n - ) 


2ARRAY 


EXP 


[ n - ) 


CONSTANT 


EXP 


[ n - ) 


2C0NSTANT EXP 


[d-) 


LARRAY 


EXP 


d-) 



Store an 8-bit value in RAM 

Fetch an 8-bit value from RAM 

Add 8-bit value to byte in RAM 

Subtract 8-bit value from a byte 
in RAM 

Indexed fetch of a ROM 
constant 

Exclusive-OR 8-bit value with 
byte in RAM 

Sets n memory cells to 0 

Fill n memory cells with n1 

Move an n-digit array in memory 

Fetch an 8-bit ROM constant 

Ex-OR value at address with n 

Store 12-bit value into a RAM 
array 

Fetch 12-bit value from RAM 

Add 12-bits to 3 RAM cells 

Subtract 12-bits from 3 nibble 
RAM array 

Add byte to a 3 nibble RAM 
array 

Subtract byte from 3 nibble array 

In-line comment definition 

Comment until end of the line 

Beginning of a colon definition 

Exit; ends any colon definition 

Index (=0) for first array element 

Index for last array element 

Begins an in-line macro 
definition 

Ends an in-line macro definition 

Allocates space for a 4-bit array 

Allocates space for an 8-bit 
array 

Defines a 4-bit constant 

Defines an 8-bit constant 

Allocates space for a long 4-bit 
array with up to 255 elements 
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4.6.7 



Assembler 
Mnemonics 



2LARRAY 


EXP 


(d~) 


Index 


EXP 


(nld addr-addr') 


ROMCONST 


EXP 


(-) 


VAKIAbLb 


cAr 


( ~ ) 


2VARIABLE 


EXP 


(-) 


<n> ALLOT 






AT <address> 




: INTx 


RET 


( - ROMAddr ) 


: $AutoSleep 






: $RESET 


EXP 


(-) 


ADD 


EXP 


( n1 n2 - n1+n2 ) 


ADDC 


EXP 


( n1 n2 - n1+n2+C ) 


CCR! 


EXP 


(n~) 


CCR@ 


EXP 


(-n) 


CMP_EQ 


EXP 


( n1 n2 - n1 ) 


CMP_GE 


EXP 


( n1 n2 - n1 ) 


CMP_GT 


EXP 


( n1 n2 - n1 ) 


CMP_LE 


EXP 


( n1 n2 - n1 ) 


CMP_LT 


EXP 


( n1 n2 - n1 ) 


CMP_NE 


EXP 


( n1 n2 - n1 ) 


CLR_BCF 


EXP 


(-) 


SET_BCF 


EXP 


(-) 


TOG_BF 


EXP 


(-) 


DAA 


EXP 


( n>9 or C set - n+6) 


DAS 


EXP 


( n - 10+/n+C ) 


DEC 


EXP 


( n - n-1 ) 


DECR 


RET 


( u I u I I — u u 1-1 


Dl 


EXP 


(-) 


DROPR 


RET 


( u | u I u - ) 


EXIT 


RET 


( ROMAddr - ) 


El 


EXP 


(-) 


IN 


EXP 


( port - data ) 



Allocates space for a long byte 
array 

Run-time array access using a 
variable array index 

Define ROM look-up table with 
8-bit values 

Allocates memory for 4-bit value 

Creates an 8-bit variable 

Allocate space for <n+1> 
nibbles of un-initialized RAM 

Fixed <address> placement 

Interrupt service routine entry 

Entry point address on Return 
Stack underflow 

Entry point on power-on reset 

Add the top two 4-bit values 

Add with Carry top two values 

Write top value into the CCR 

Fetch the CCR onto top of stack 

If n1=n2, then Branch flag set 

If n1>=n2, then Branch flag set 

If n1>n2, then Branch flag set 

If n1<=n2, then Branch flag set 

If n1<n2, then Branch flag set 

If n1on2, then Branch flag set 

Clear Branch and Carry flag 

Set Branch and Carry flag 

Toggle the Branch flag 

BCD arithmetic adjust [addition] 

9's complement for BCD 
subtract 

Decrement top value by 1 

Decrement value on the Return 
Stack 

Disable interrupts 

Drop element from Return Stack 

Exit from current ":"-definition 

Enable interrupts 

Read data from an I/O port 
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INC 

NOP 

NOT 

RP! 

RP@ 

RTI 

SLEEP 



EXP 
EXP 
EXP 
XP( 
EXP 

RET 
EXP 



SWIO SWI7 EXP 



SP! 
SP@ 
SUB 
SUBB 

TABLE 



EXP 
EXP 
EXP 
EXP 

EXP 
RET 



OUT 


EXP 


data port - ) 


X@ 


EXP 


(~d) 


[X]@ 


EXP 


(-n) 


[+X]@ 


EXP 


(~n) 


[X-]@ 


EXP 


(-n) 


[>X]@ $xx 


EXP 


(~n) 


X! 


EXP 


(d~) 


[X]! 


EXP 


(n-) 


[+X]! 


EXP 


(n-) 


[X-]! 


EXP 


(n-) 


[>X]! $xx 


EXP 


[n-) 


Y@ 


EXP 


(~d) 


[Y]@ 


EXP 


!-n) 


[+Y]@ 


EXP 


(-n) 


[Y-]@ 


EXP 


(-n) 


[>Y]@ $xx 


EXP 


(-n) 



n - n+1 ) 

-) 

n - In ) 

--) 
-d) 

RETAddr - ) 

-) 

-) 

d-) 

-d) 

n1 n2 - n1-n2 ) 
n1 n2 - n1+/n2+C ) 

-d) 

RetAddr RomAddr -) 



Increment the top value by 1 
No operation 

1 's complement of the top value 

Store as Return Stack Pointer 

Fetch current Return Stack 
Pointer 

Return from interrupt routine 

Enter "sleep-mode", enable all 
interrupts 

Software triggered interrupt 

Store as Stack Pointer 

Fetch current Stack Pointer 

2's complement subtraction 

1's complement subtract with 
Borrow 

Fetches an 8-bit constant from 
an address in ROM 

Write data to I/O port 

Fetch current x register contents 

Indirect x fetch of RAM contents 

Pre-increment x indirect RAM 
fetch 

Post-decrement x indirect RAM 
fetch 

Direct RAM fetch, x addressed 

Move 8-bit address to x register 

Indirect x store of RAM contents 

Pre-increment x indirect RAM 
store 

Post-decrement x indirect RAM 
store 

Direct RAM store x addressed 

Fetch current Y register contents 

Indirect Y fetch of RAM contents 

Pre-increment Y indirect RAM 
fetch 

Post-decrement Y indirect RAM 
fetch 

Direct RAM fetch, Y addressed 
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VI 

Y ! 


CAr ( U ~ 


) 


[Y]! 


EXP ( n - 


) 


[+Y]! 


EXP ( n - 


) 


[Y-]! 


EXP ( n - 


) 


[>Y]! Sxx 


EXP ( n - 


) 


>RP $xx 


EXP ( - ) 




>SP $xx 


EXP(-) 




>X $xx 


EXP ( - ) 




>Y Sxx 


EXP(-) 





Move address to Y register 

Indirect Y store of RAM contents 

Pre-increment Y indirect RAM 
store 

Post-decrement Y indirect RAM 
store 

Direct RAM store, Y addressed 
Set Return Stack Pointer 
Set Expression Stack Pointer 
Set x register immediately 
Set Y register immediately 
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4.7 Short Form 
Dictionary 



Table 4-1. MARC4 - Control Commands 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


1 


AGAIN 


3 










CY 


B 




BEGIN 


0 
















DO 


1 


limit index- 


-- limit index 












#DO 


1 


index- 


-- u u index 












?DO 


5 


limit index- 


- u limit index 






CY 


B 




LOOP 


9 


-- (n1 n2 n3) -- 


-- (-1 level) -- 






CY 


B 




#LOOP 


4 




u u index- 
u u index- 1 








B 




+LOOP 


10 


n - 


u limit index- 
ii limit index+n 

LI 1 1 1 1 1 1 1 II IVJwAT 1 1 






CY 


B 




? LEAVE 


2 
















-7LEAVE 


3 












B 




REPEAT 


3 










CY 


B 




UNTIL 


3 












B 




WHILE 


3 












B 




CASE 


o 
















ELSE 


3 










CY 


B 




ENDCASE 


1 


n -- 














ENDOF 


3 










CY 


B 




EXECUTE 


3 


ROMaddr — 


— (2+x level)— 












IP 


3 












B 




OF 


4 


n1 — n1 n2 — (n1 ) 








CY 


B 




THEN 


o 










CY 


B 




CCR@ 


1 


— n 














CCR! 


1 


n - 








CY 


B 


1 


CLR_BCF 


2 


--(1 level)- 








CY 


B 




El 


2 










CY 


B 


1 


EXIT 


1 




oldPC -- 












Dl 


1 














1 


SET_BCF 


1 










CY 


B 




SWI0..SWI7 


4 


- (2 level) -- 












1 


TOG_BF 


1 












B 
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Table 4-2. MARC4 - Mathematic Commands 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


I 


ADD 


1 


n1 n2 -- n1+n2 








CY 


B 




+ 


1 


n1 n2 -- n1+n2 








CY 


B 




+! 


4 


n addr — 




X 


Y 


CY 


B 




INC 


1 


n — n+1 










B 




1 + 


1 


n — n+1 










B 




1+! 


4 


addr — 




X 


Y 




B 




ADDC 


1 


n1 n2 -- n1+n2+CY 








CY 


B 




+C 


1 


n1 n2 -- n1+n2+CY 








CY 


B 




D+ 


7 


d1 d2 -- d1+d2 


- (1 level) - 






CY 


B 




D+! 


8 


d addr -- 


- (1 level) - 


X 


Y 


CY 


B 




M+ 


5 


d n -- d+n 


- (1 level) - 






CY 


B 




T+! 


19 


nh nm nl addr 
-- (1 level) -- 


- (2 level) - 


X 


Y 


CY 


B 




TD+! 


20 


d addr — (1 level) — 


- (2 level)- 


X 


Y 


CY 


B 




DAA 


1 


n — n+6 








CY 


B 




SUB 


1 


n1 n2 - n1-n2 








CY 


B 






1 


n1 n2 - n1-n2 








CY 


B 




DEC 


1 


n — n-1 










B 




1- 


1 


n — n-1 










B 




1-! 


4 


addr — 




X 


Y 




B 




SUBB 


1 


n1 n2 -- n1+/n2+CY 








CY 


B 




-C 


1 


n1 n2 - n1+/n2+CY 








CY 


B 




D- 


8 


d1 d2 - d1-d2 


- (1 level) - 






CY 


B 




D-! 


10 


d addr -- 


- (1 level) - 


X 


Y 


CY 


B 




M- 


5 


d1 n -- d1-n 


- (1 level) - 






CY 


B 




T-! 


22 


nh nm nl addr 
-- (1 level) -- 


- (2 level) - 


X 


Y 


CY 


B 




TD- 


22 


d addr — (1 level) — 


- (2 level) -- 


X 


Y 


CY 


B 




DAS 


3 


n -- 9-n 








CY 


B 




2* 


1 


n - n*2 








CY 


B 




D2* 


4 


d - d*2 








CY 


B 




21 


1 


n — n/2 








CY 


B 




D2/ 


4 


d - d/2 








CY 


B 




CMP EQ 


1 


n1 n2 — n1 








CY 


B 






2 


n1 n2 -- 








CY 


B 




0= 


3 


n — 








CY 


B 




D= 


13 


d1 d2 -- 


- (1 level) - 






CY 


B 




D0= 


2 


d-- 










B 




CMP_GE 


1 


n1 n2 -- n1 








CY 


B 




D>= 


19 


d1 d2 -- 


-- (1 level u d2h d2l) -- 






CY 


B 




CMP_GT 


1 


n1 n2 -- n1 








CY 


B 
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Table 4-2. MARC4 - Mathematic Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


D 


1 

1 


> 


o 
d 


n1 n2 — 








OY 


D 




u> 


16 


d1 d2 — 


— (1 level u d2n d2l) ~ 






OY 


D 

D 




UIVIr_Lb 


1 


m wd — m 








UY 


D 




<= 


2 


n1 n2 — 








OY 


D 

D 




U<= 


1 9 


/J -1 /JO 

ai a<i — 


— (l level u odn OA) — 






OY 


D 




Clvlr_LI 


1 


n1 n2 — n1 








OY 


D 

D 




< 


o 
d 


n1 n2 — 








UY 


D 




u< 


16 


d1 d2 — 


— (1 level u d2n d2l) — 






OY 


D 
D 




OMr_Nt 


1 


m — m 








Or 


D 




<> 


2 


n1 n2 — 








CY 


D 
D 




o 

U<> 


o 

o 


n — 








UY 


D 




D0<> 


3 


a — 










D 
D 




JO 


1 (J 


/J -1 /JO 

dl ad — 


— (i level) — 






UY 






K A A V 

MAX 


7 


n1 n2 — nmax 


/■i l/%w/*l\ 

— (1 level) — 






OY 


D 

D 




rM\ n a v 
UMAX 


on 
OU 


/Ji /JO /JH /JH /JO /Imnu 

ui u<i -ai ai ad— amax 


— (o level) — 






UY 


D 




h Jl 1 M 

MIN 


7 


n1 n2 — nmin 


— (1 level) — 






OY 


D 

D 




UMIN 


on 


/Ji /JO /J H /Ji /JO /Jmit-i 

ai CiV --ai ai a<£— amin 


— (o level) — 






w 

UY 


D 




M [^/^ ATI — 

NhCjAI b 


2 


n1 — n1 










D 

D 




UNbtaAl b 


o 
O 


/j /j 
a — a 


— (i level) — 






UY 


D 




NO 1 


1 


nl — /n1 










D 
D 




HOL 


1 










UY 


D 




□AD 

KOH 


1 










CY 


D 
D 






1 


n — n*2 








UY 


D 




nun 

bHH 


1 


n — n/2 








OY 


D 

D 




AND 


1 


n1 n2 — n1 and n2 










D 




UK 




n1 n2 — n1 v n2 










D 




XOR 




n1 n2 - n1 xor n2 










B 




TOGGLE 


4 


n1 addr- 




X 


Y 




B 




D>S 


2 


d- n 














S>D 


2 


n--d 
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Table 4-3. MARC4 - Memory Commands 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


I 


@ 


2 


addr — n 




X 


Y 








2@ 


3 


addr — nh nl 




X 


Y 








3@ 


4 


addr — nh nm nl 




X 


Y 








X@ 




-- Xh XI 














[XI @ 


1 


— n 














r+xi @ 


1 


— n 




X 










rx-i @ 


1 


— n 




X 










Y@ 


1 


-- Yh Yl 














[Yl@ 

L 1 J v -' 


1 


— n 














r+Yi @ 

L 1 1 J ^" 


1 


— n 






Y 








L 1 J v 


1 


— n 






Y 








DTABLE @ 


14 


ROMaddr n - nh nl 


-- (2 level) - 






CY 


B 




TABLE 


1 


— nh nl 


(2 level) - 












ROMBYTE® 


2 


ROMaddr -- nh nl 


-- (2 level) - 












! 


2 


n addr— 




X 


Y 








2! 


4 


nh nl addr — 




X 


Y 








3! 


7 


nh nm nl — 


- (1 level) - 


X 


Y 








X! 


1 


Xh XI -- 




X 










rxr 


1 


n — 














[+XV 

L 1 / V J - 


1 


n — 




X 










fX-1! 

L' x J" 


1 


n — 




X 










Y! 


1 


Yh Yl - 






Y 








IY|i 

L 1 J - 


1 


n — 














f+Yl! 

L 1 1 J" 


1 


n — 






Y 








fY-li 

L 1 J" 


1 


n — 






Y 








ERASE 


14 


addr n— 


-- (2 level) - 


X 


Y 




B 




FILL 


24 


addr n1 n2 — 


- (3 level) - 


X 


Y 




B 




MOVE 


14 


n from to - 


- (2 level) - 


X 


Y 








MOVE> 


10 


n from to - 


- (2 level) - 


X 


Y 








IN 


1 


port - data 










B 




OUT 


1 


data port - 
















3 


- - ROMaddr 
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Table 4-4. MARC4 - Commands 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


I 


! 


2 


n addr- 




X 


Y 








#DO 


1 


index- 


- u u index 












#LOOP 


4 




u u index- 
u u index-1 








B 




+LOOP 


10 


n - 


u limit index- 
u limit index+n 






CY 


B 




-7LEAVE 


3 












B 




<ROT 


2 


n1 n2 n3 - n3 n1 n2 














>RP xxh 


2 
















>SP xxh 


2 
















?DO 


5 


limit index— 


— u limit index 






CY 


B 




?DUP 


5 


n — n n 








CY 


B 




? LEAVE 


2 
















@ 


2 


addr — n 




X 


Y 








L 1 / V J - 




n — 




X 










r+xi @ 


1 


— n 




X 










r+Yl! 

L 1 1 J" 


1 


n — 






Y 








r+Yi@ 

L 1 1 J ^" 


1 


— n 






Y 








rx-T 

L' x J" 


1 


n — 




X 










rx-i@ 


1 


— n 




X 












1 


n — 
















1 


— n 














fY-1! 

L 1 J" 


1 


n — 






Y 








rY-i@ 

L 1 J 


1 


— n 






Y 








IY|i 

L 1 J - 


1 


n — 














I i j \^ 


1 


— n 














2! 


4 


nh nl addr — 




X 


Y 








2<ROT 


14 


d1 d2 d3 -- d3 d1 d2 


- (4 level) -- 












2@ 


3 


addr — nh nl 




X 


Y 








2DROP 


2 


n1 n2 — 














2DUP 


2 


d - d d 














2NIP 


4 


d1 d2 - d2 














20VER 


8 


d1 d2 -d1 d2 d1 


- -(2 level u n2 n1) - 












R@ 


1 


-- n 


u u n — u u n 












2R@ 


1 


- n1 n2 


u n1 n2 — u n1 n2 












2 ROT 


8 


d1 d2 d3 - d2 d3 d1 


- (1 level u d1) - 












2SWAP 


8 


d1 d2 - d2 d1 


- (1 level u u d2l) - 












2TUCK 


6 


d1 d2 - d2 d1 d2 


- (1 level d1l d2) - 












3! 


7 


nh nm nl addr- 


- (1 level) - 


X 


Y 








3@ 


4 


addr - nh nm nl 




X 


Y 








3DROP 


3 


n1 n2 n3 - 
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Table 4-4. MARC4 - Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


V 

A 


Y 


CY 


D 


1 


OP\l ID 

oUUr 


A 

4 


nin^rw — m n^nom n^no 


— (n l nd no) — 












3R@ 


1 


— n1 n2 n3 


n3 n2 n1 — n3 n2 n1 












Dj a a 
UAA 


A 


n — n+6 








OY 


D 




ADD 


1 


n1 n2 — n1 +n2 








OY 


D 




+ 


-1 
1 


m r\d — m +n^! 








OY 


D 




, 1 

+! 


4 


n addr — 




X 


\/ 
Y 


OY 


D 
D 




1 MO 

INO 


1 


n — n+1 










D 
D 




1 + 


1 


n — n+1 










D 
D 




-i ■ i 
1 +! 


4 


addr — 




v 
A 


\/ 
Y 




D 
D 




A P\P\0 

ADDG 


1 


nl n2 — n1+n2+OY 








OY 


D 
D 




+o 


1 


m iv — m+rv+OY 








OY 


D 




D+ 


7 


/J H JO JH ■ /JO 

dl d2 — dl +d2 


/ A |_. ,_|\ 

— (1 level) — 






OY 


D 




U+! 


o 
O 


d addr — 


l A lnunl\ 

— (1 level) — 


v 
A 


Y 


OY 


D 
D 




DAb 


3 


n — 9-n 








OY 


D 
D 




Ol in 
bUb 


H 
1 


m n<i — m-n^ 








OY 


D 
D 






1 


n1 n2 — n1-n2 








OY 


D 




DbG 


A 
\ 


n — n-1 










D 
D 




1 - 


1 


n — n-1 










D 
D 




H 1 


A 
4 


addr — 




v 
A 


\/ 
Y 




D 
D 




Ol HDD 

bUbb 


1 


nl n2 — m+/n2+OY 








OY 


D 
D 




o 
-Li 


A 
1 


ni iv — m+/iv+OY 








OY 


D 
D 




D- 


8 


j-J H ^JO <-J H /JO 

dl d2 — dl-d2 


— (1 level) — 






OY 


D 
D 




p\ l 

U-! 


1 U 


d addr — 


I A lnunl\ 

— (i level) — 


v 
A 


Y 


OY 


D 
D 




2 


1 


n — n*2 








OY 


D 




Ud 


A 

4 


a — a d 








OY 


D 




2/ 


1 


n — n/2 








OY 


D 




Udl 


4 


ri Aft 

a — old 








OY 


D 




A /"* A 1 hi 

AbiAIN 


3 










OY 


D 
D 




Aim 
AND 


A 
\ 


n1 n2 — n1 and n2 










D 
D 




bbCalN 


0 
















PACT 

OAbb 


n 
U 


n — n 














OGH! 


1 


n — 








OY 


D 


1 
1 




A 
\ 


— n 














Ol 1 — ) nnr 


2 


/ A | M M | \ 

- - ( 1 level ) - - 








OY 


D 




OMr_bU 


A 


m n^ — m 








OY 


D 
D 






2 


n1 n2 — 








OY 


b 




n— 

U— 


O 


n — 








PY 


R 
D 




D= 


13 


d1 d2 -- 


- (1 level) - 






CY 


B 




D0= 


2 


d - 










B 




CMP_GE 


1 


n1 n2 -- n1 








CY 


B 




>= 


2 


n1 n2 -- 








CY 


B 
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Table 4-4. MARC4 - Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


D 


1 


u>= 




CI1 Od — 


— (i level u u^n ad\) — 






OY 


D 




OMr_Ca 1 


1 


n1 n2 — n1 








CY 


D 
D 




> 


d 


n1 n2 — 








UY 


D 
D 




D> 


16 


d1 d2 — 


— (1 level u d2n d2l) — 






CY 


D 




a d i 

OMr_Lb 




m x\d. — m 








CY 


D 
D 




<= 


2 


n1 n2 — 








CY 


D 




U<= 


ly 


dl d*; — 


/^ Inwnl ii ^JOI-i ^IOI\ 

— (i level u u^n u^i) — 






UY 


D 
D 




OMI-^LI 


1 


n1 n2 — n1 








OY 


D 
D 




< 


d 


n1 n2 — 








UY 


D 
D 




U< 


16 


d1 d2 — 


— (1 level u d2n d2l) — 






OY 


D 
D 




OMr_Nb 


H 
1 


m n^ — m 








UY 


D 
D 




<> 


2 


n1 n2 — 








OY 


D 
D 




U<> 


3 


n — 








r> w 

UY 


D 




Do 


10 


d1 d2 — 


/-| lmml\ 

— (1 level) — 






OY 


D 
D 




DUO 


o 

3 


d ~ 










D 
D 




DbCH 


1 




u u n — u u n-1 








D 
D 




Dbr 1 n 


y 


/ODt, cdi cnu cnh •-. 

-(orn brl bUn bul)— n 


— (i level) — 






OY 


D 




rM 
Ul 


1 














1 
1 


r*IV A A V 

UMAX 


30 


A~i A*~i A-\ A~i A>~i Arv\r\*i 

al ad —a\ al ad— amax 


/O lmml\ 

— (3 level) — 






UY 


D 




rift aim 
DMIN 


30 


dl d2 — dl dl d2— dmin 


In lmml\ 

— (3 level) — 






OY 


D 




DNbtaAl b 


o 
8 


A A 

a — d 


— (i level) — 






OY 


D 
D 




DO 


1 


limit index— 


— limit index 












UHUr 


1 


n ~ 














UKOrK 


1 




u u u — 












U lAbLblS 


-1 /I 

14 


ROMaddr — const.h const. I 


/O lmml\ 

— (d level) — 






OY 


D 




U 1 OCabLb 


8 


d addr -- 


l-i lmml\ 

— (1 level) - 


X 


Y 




D 




rM id 


1 


n1 — n1 n1 














bl 


2 










OY 


D 
D 


1 
1 


bLbb 


3 










OY 


D 
D 




i^m r~\^ a o rr 

bNDOAbb 


1 


n — 














bNUUr 


o 

3 










UY 


D 
D 




1 — 1 — ) A O [ — 

hKAbt 


14 


addr n— 


/O Im ml\ 

— (2 level) — 


X 


Y 




D 
D 




bAl 1 






oldKo — 












bXbOU 1 b 


3 


HOMaddr - - 


— (2 + x level) ~ 












ci i i 
rILL 


<;4 


addr n1 n2 — 


/O lmml\ 

— (3 level) — 


V 

X 


Y 




D 




1 


1 


— index 


u u index— u u index 












In 


o 












R 
D 




IN 


1 


port -- data 










B 




INDEX 


8 


n addr -- 


- (1 level) - 






CY 


B 




J 


6 


-- J 


- (-1 level) -- 












LOOP 


9 


-(n1 n2 n3)- 


- (-1 level) - 






CY 


B 
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Table 4-4. MARC4 - Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


1 


M+ 


r- 

o 


d1 n — d1 +n 


/-I lnunl\ 

— (i level) — 






r"*V 
OY 


D 
D 




iv n 

M- 


5 


d1 n — dl-n 


— (1 level) — 






OY 


D 




UAV 

MAX 


—j 

I 


n1 n2 — nmax 


/-I lmml\ 

— (i level) — 






OY 


D 




MIN 


7 


n1 n2 — nmin 


/ -t |_. ,_|\ 

— (1 level) — 






OY 


D 




MUVb 


-1 A 

14 


n from to — 


— (d level) — 


X 


Y 








MOVb> 


10 


n from to — 


tt~i lmml\ 

— (2 level) — 


X 


Y 








NbljAI b 


d 


n -1 t-i -1 

m — m 










D 
D 




MID 

NIP 


2 


n1 n2 — n2 














U>b 


d 


d — n 














M/""\D 

NOP 


1 
















m/"yt 
NU 1 


H 
1 


t-i-1 In -1 

m — /m 










D 




Or 


4 


n1 n2 — 








OY 


D 
D 




UH 


H 
1 


n1 n2 — n1 v n2 










D 




/"M IT 

OU 1 


1 


data port — 














r\\ /c: d 
UVbH 


1 


r\d m — n<^ m r\d 














HICK 


13 


x -(2 level)- n[x] 


/O Im ml\ 

— (2 level) — 


X 


Y 


OY 


D 




>H 


-i 


m 


— u u n1 












2>H 


1 


n1 n2 — 


— u n2 n1 












3>H 


1 


m r\d no — 


— no n*i m 












Dw 

H> 


2 


— n 


u u n — 












^H> 


d 


— n1 n2 


u n2 n1 — 












3K> 


2 


— n1 n2 n3 


n3 n2 n1 — 












HUbP 1 n 


1o 


- \d level) - n 


/-I UunlV 

— (i level) — 






r"*V 
OY 


D 




nrnr at 

HbPbAI 


3 










OY 


D 




n r n [ — i — 
nrnbb 


oU 


/O Ini iaI\ 

- (o level) - n 


— (d level) — 






r"*V 
OY 


D 
D 




HOL 


1 










OY 


D 




D/~il 1 

HULL 


rr—7 
Of 


x levei)- 


— (4 level) — 


V 

X 


Y 


OY 


D 


1 
1 


HOMdY 1 b@ 


2 


ROMaddr — conh conl 


/O Im ml\ 

— (2 level) ~ 












□An 

HUH 


-i 










OY 


D 
D 




HO 1 


1 


n1 n2 n3 — n2 n3 n1 














DDI 

HP! 


H 
1 


nnL, DDI 

HPn HPI — 














D D 

HP @ 


1 


n nu ddi 

— HPn HPI 














b>U 


d 


n — a 














bb 1 _bsCr 


1 










OY 


D 

D 




O L_l 1 

bnl_ 


H 
1 


n — n*2 








OY 


D 




ni in 

bHH 


1 


n — n/2 








OY 


D 




Or! 


I 


op n cpi 
Or II or I 














SP@ 


1 


- SPh SPI+1 














SWAP 


1 


n2 n1 - n1 n2 














SWI0..SW17 


4 


-- (2 level) -- 












1 


T+! 


19 


nh nm nl addr- (1 level) -- 


-- (2 level) -- 


X 


Y 


CB 


B 
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q FORTH Language Dictionary 

Table 4-4. MARC4 - Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


D 


1 

1 


T 1 

I-! 


iLd. 


nh nm nl addr — 


— level) — 


V 

A 


Y 


r->\/ 
OY 


D 




1 U+! 


20 


d addr — (1 level) — 


/O lmml\ 

— (2 level) — 


v 

X 


Y 


OY 


D 




1 LH 


lid. 


d addr — (1 level) — 


— (d level) ~ 


V 

X 


Y 


OY 


D 




-ri I i~k I 

THbN 


0 










OY 


D 
D 




1 Ulj_br 


-i 












D 






4 


n1 addr — 




v 

X 


Y 




D 
D 




Tl IPI/ 




m n<i — n<^ m n<i 














1 1 N ITI 1 

UN TIL 


3 












D 




\ A /I 1 1 1 d 

WMILb 


o 
O 












D 
D 




VI 

a! 


H 
1 


V^ VI 

xn xi — 




V 

X 










X@ 


1 


-- Xh XI 














XOR 


1 


n1 n2 - n1 xor n2 






Y 








Y! 


1 


Yh Yl -- 














Y@ 


1 


-- Yh Yl 















Tab/e 4-5. MARC4 - STACK Commands 



Command 


Bytes 


Expression Stack 


Return Stack 


X 


Y 


CY 


B 


I 


DECR 


1 




u u n - u u n-1 








B 




DEPTH 


9 


-(SPh SPI SOh S0l)--n 


-- (1 level) -- 






CY 


B 




DROP 


1 


n1 -- 














2DROP 


2 


n1 n2 -- 














3DROP 


3 


n1 n2 n3 -- 














DROPR 


1 




u u u -- 












DUP 


1 


n1 -- n1 n1 














?DUP 


5 


n -- n n 








CY 


B 




2DUP 


2 


d--dd 














3DUP 


4 


n1 n2n3 --n1 n2n3n1 n2n3 


-(n1 n2 n3)- 












1 


1 


- index 


u u index-u u index 












INDEX 


8 


d/n addr -- 


-- (1 level) -- 






CY 


B 




J 


6 


-J 


- (-1 level) -- 












NIP 


2 


n1 n2 -- n2 














2NIP 


4 


d1 d2 -- d2 














OVER 


1 


n2 n1 - n2 n1 n2 














20VER 


8 


d1 d2 -d1 d2 d1 


-- (2 level u n2 n1) -- 












PICK 


13 


x -(2 level)- n[x] 


-- (2 level) -- 


X 


Y 


CY 


B 




R@ 




-- n2 


u u n1 - u u n1 












2R@ 




-- n1 n2 


u n1 n2 - u n1 n2 












3R@ 




-- n1 n2 n3 


n3 n2 n1-- n3 n2 n1 












>R 




n1 


-- u u n1 












2>R 




n1 n2 -- 


- u n2 n1 












3>R 




n1 n2 n3 -- 


-- n3 n2 n1 
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q FORTH Language Dictionary 



Table 4-5. MARC4 - STACK Commands (Continued) 



Command 


Bytes 


Expression Stack 


Return Stack 


V 
A 


Y 


CY 


D 


1 

1 


D^ 

hi> 


2 


— n 


u u n — 












2H> 


2 


— n1 n2 


u n2 n1 — 












oH> 


2 


— ni no 


no n2 m — 












I— I r~n— nTi I 

HDbr 1 H 


13 


/O 1 i-M l\ n 

-(2 level)- n 


— (1 level) — 






OY 


D 
D 




nrnbb 


ol) 


-(o level)- n 


/O lmml\ 

— (2 level) — 






OY 


D 
D 




HO 1 


1 


n1 n2 n3 — n2 n3 n1 














2HO 1 


0-7 


di d2 do — d2 do d i 


— (1 level udi)- 












<HO 1 


2 


n1 n2 n3 — n3 n1 n2 














2<HO 1 


14 


di d2 do — do d i d2 


— (4 level) — 












HP @ 


1 


nnL DDI 

— Hrn Hrl 














nni 

Hr! 


1 


DDl-^ DDI 

Hrn Hrl — 














br@ 


1 


O DU O DI , H 

brh brl+1 














GDI 

Or! 




CDh ODI 

brn brl — 














SWAP 




n2 n1 - n1 n2 














2SWAP 


8 


d1 62 - d2 d1 


- (1 level u u d2l) - 












TUCK 


2 


n1 n2 -- n2 n1 n2 














2TUCK 


6 


d1 62 - 62 d1 d2 


-- (1 level d1l d2) -- 
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4.8 Detailed 

Description of 
the qFORTH 
Language 

4.8.1 Store 



Purpose: Stores a 4-bit value at a specified memory location. 

Category: qFORTH macro 

Library Implementation: CODE ! Y! ( n addr -- n ) 

[Y]l ( n - ) 

END-CODE 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Changes in the actually generated code sequence can result 
due to the compiler optimizing techniques (register tracking) 

EXP ( n RAM_addr - ) 

RET ( - ) 

EXP: 3 elements are popped from the stack 

RET: not affected 

Not affected 

The contents of the Y or X register may be changed 
2 

+! 2! 3! @ 
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q FORTH Language Dictionary 



Example: 

VARIABLE ControlState 
VARIABLE Semaphore 

: InitVariables ( initialize VARs ) 

0 ControlState ! ( Set up control flag ) 

2 Semaphore ! ( Set up a preset value ) 
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4.8.2 tick Purpose: Leaves a compiled ROM code address on the EXP stack. 

Used in the form ' <name>. 

' searches for a name in the qFORTH dictionary and returns 
that name's compilation address (code address). If the name 
is not found in the dictionary, an error message results. 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

Bytes Used: 
See Also: 



Control structure 

EXP (--ROM_addr ) 

RET ( - ) 

EXP: 3 nibbles are pushed on the stack 

RET: not affected 

Not affected 

3 

EXECUTE 
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q FORTH Language Dictionary 



Example: 



' is typically used to initialize the content of a variable with the code address of the 
qFORTH word for vectored execution. 



For example, a program might contain a variable named $ERROR which would specify 
the action to be taken if a certain type of error occurred. At compilation time, $ERROR is 
"vectored" with a sequence such as 



and the main program, if it detects an error, can execute the sequence 

$ERROR 3@ EXECUTE 
to invoke the error handler. 

This program's error-handling routine can be changed "on the fly" by changing the 
address stored in $ERROR without modifying the main program in any way. 



3 ARRAY $ERROR 



ERROR-ROUTINE $ERROR 3! 
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#D0 



4.8.3 



Hash-DO 



Purpose: 



#DO indicates the start of an iterative "decrement-if-nonzero" 
loop structure. It is used only within a macrocolon definition in 
a pair with #LOOP. The value on top of the stack at the time 
#DO is executed determines the number of times the loop 
repeats.The value on top is the initial loop index which will be 
decremented on each iteration of the loop (see example 2). 

If the current loop index I is not accessed inside of a loop 
block, this control structure executes much faster than an 
equivalent n 0 DO ... LOOP. The standard FORTH-83 loop 
structure n 0 DO ... -1 +LOOP maps directly to the behavior 
of the n #DO ... #LOOP structure. 



Category: 



Control structure/qFORTH macro 



Library Implementation: CODE #DO >R 

$#DO: 
END-CODE 
EXP ( Index -- ) 
RET(-ulullndex ) 
EXP: 1 element is popped from the stack 
RET: 1 element is pushed onto the stack 
#DO : Not affected 
#LOOP : CARRY flag not affected 

BRANCH flag = Set, if (Index- 1 <> 0) 

Not affected 
1 

#LOOP 7LEAVE -7LEAVE 



Stack Effect: 
Stack Changes: 
Flags: 



X Y Registers: 
Bytes Used: 
See Also: 
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q FORTH Language Dictionary 



#D0 



Example 1 : 

8 ARRAY result ( 8 digit BCD number ) 

: ERASE ( Fill a block of memory with zero ) 

<ROT Y! ( addr count -- ) 

0[Y]!1- ( count - count- 1 ) 

#DO 

0 [+Y]! ( Use the MARC4 pre-incremented store ) 

#LOOP ( REPEAT until length-1 = 0 ) 

> 

: Clear_Result 

Result 8 ERASE ( Clear result array ) 



Example 2: 

1 CONSTANT portl 
: HASH-DO-LOOP 

0 #DO (loop 16 times ) 

11- portl OUT ( write data to 'portl': F, E, D, C... 1,0. ) 

#LOOP ( repeat the loop. ) 
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q FORTH Language Dictionary 



#LOOP 



4.8.4 



Hash-LOOP 



Purpose: 



#LOOP indicates the end of an iterative "decrement-if-non- 
zero" loop structure. #LOOP is used only within a colon 
definition in a pair with #DO. The value on top of the stack at 
the time #DO is executed determines the number of times the 
loop repeats. The loop index is decremented on the Return 
Stack on each iteration, i.e., the execution of the #LOOP 
word, until the index reaches zero. If the new index is decre 
mented to zero, the loop is terminated and the loop index is 
discarded from the Return Stack. Otherwise, control 
branches back to the word just after the corresponding #DO 
word. 

If the current loop index I is not used inside a loop block this 
structure executes much faster than an equivalent DO 
...LOOP. The behavior of the standard FORTH loop 
structure 0 DO ... -1 +LOOP is identical to the #DO ... #LOOP 
structure. 



Category: 



Control structure/qFORTH macro 
Library Implementation: CODE #LOOP DECR ( decrement loop index on RET ) 

(S)BRA _$#DO 
_$LOOP: DROPR ( drop loop index from RET ) 
END-CODE 
EXP ( - ) 

IF lndex-1 > OTHEN RET (u I u I Index -u I u| lndex-1) 
ELSE RET ( u | u | Index -- ) 
EXP: Not affected 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



RET: If #LOOP terminates, top element is popped from the 
stack 

CARRY flag not affected 

BRANCH flag set as long as index-1 <> 0 

Not affected 

3-4 

#DO 7LEAVE -7LEAVE 
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q FORTH Language Dictionary 



#LOOP 

Example: 

16 ARRAY LCD-buffer 

: FILL-IT Y! ( n count addr - n count ) 

#DO ( end address was on stack ) 

DUP [Y-]! ( duplicate and store value ) 

#LOOP 
; Setup_Full_House 
Fh 0 LCD-buffer [15] FILL-IT 
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$AUTOSLEEP 



4.8.5 Autosleep Purpose: The $AUTOSLEEP function will automatically be placed at 

ROM address $000 by the compiler and may be redefined 
slightly by the user. The Return Stack pointer is initialized in 
$RESET to FCh. After the last interrupt routine is processed 
and no other interrupt is pending, the PC is automatically 
loaded to the address $000 ($AUTOSLEEP). This forces the 
MARC4 into sleep mode through processing the $AUTOS 
LEEP routine. This sleep mode is a shutdown condition 
which is used to reduce the average system power 
consumption, whereby the CPU is halted. 

The internal RAM data stays valid during sleep mode. To 
wake up the CPU again, an interrupt must be received from a 
peripheral module (timer/counter or external interrupt pin). 
The CPU starts running at the ROM address where the 
interrupt service routine is placed. 

Attention: It is not recommended to use the SLEEP 
instruction other than in the $RESET or $AUTOSLEEP 
because it might result in unwanted side effects within other 
interrupt routines. If any interrupt is active or pending, the 
SLEEP instruction will be executed in the same way as an 
NOP! 

Category: Interrupt handling/predefined qFORTH colon definition 

Library Implementation: : $AUTOSLEEP 

$TIRED: NOP 

SLEEP 
SET_BCF 
BRA_$TIRED 
[E0R0] 



Stack Effect: 
Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP & RET empty 

EXP: not affected 

RET: not affected 

SLEEP sets the LENABLE flag 

CARRY and BRANCH flags are set by $AUTOSLEEP 

Not affected 

4 

$RESET, INTO ... INT7, Dl, El, RTI, SLEEP 
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q FORTH Language Dictionary 



$AUTOSLEEP 



Example: 

\ Improved $AUTOSLEEP routine for noisy environment 

: Clr_INT_controller 
;; RTI [N] 

:$AUTOSLEEP 
$_Tired: NOP 
SLEEP 

NOP SET_BCF 



CPr_INT_controller 



\ Clear unwanted spurious 
\ INT pending/active bits 



BRA $_Tired [EO RO] 
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q FORTH Language Dictionary 



$RESET 



4.8.6 Dollar-reset 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



The power-on-reset colon definition $RESET is placed at ROM 
address $008 automatically and is re-definable by the user. The 
maximum length of this part in the Zero Page is 56 bytes when 
INTO is also used. 

It is normally used to initialize the two stack pointers as well as 
the connected I/O devices, like timer/counter, LCD and A/D- 
converter. 

An optional SELFTEST is executable on every power-on-reset if 
Port 0 is forced to a customer specified input value. 

Interrupt handling/predefined qFORTH colon definition 

EXP stack pointer initialized 

RET stack pointer initialized 

EXP: empty 



RET: empty 
CARRY 
BRANCH 
LENABLE 
Not affected 

Modified by the customer 
$AUTOSLEEP 



flag undefined after power-on reset 
flag undefined after power-on reset 
flag reset by hardware during POR- 
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$RESET 

Example: 

0 CONSTANT portO 

FCh 2CONSTANT NoRAM 

VARIABLE SO 1 6 ALLOT ( Define expression stack space. ) 
VARIABLE RO 31 ALLOT ( Define RET stack ) 



: $RESET ( Possible $RESET implement, of a customer ) 

>RP NoRAM ( Init RET stack pointer to non-existent memory ) 

>SP SO ( Init EXP stack pointer; above RET stack ) 

PortO IN 0= 
IF 

Selftest 
THEN 

lnit_Peripherals 
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( comment) \ 



4.8.7 Paren, Backslash Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Begins a comment, used either in the form 
( ccccc) or \ comment is rest of line 

The characters "ccccc" delimited by the closing parenthesis 
are considered a comment and are ignored by the qFORTH 
compiler. The characters "comment is rest of line" are 
delimited by the end of line control character(s). 

Note: The " ( " and " \ " characters must be immediately preceded 
and followed by a blank. Comments should be used freely 
for documenting programs. They do not affect the size of 
the compiled code. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

% 
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( comment) \ 

Example: 

: ExampleWord 

13 (--13 ) 

DUP ( ******* This is a qFORTH comment ***** ) 

ROT \This is a comment until the end of line. 

SWAP (331-313 ) 

3DROP ( clean table again. ) 

; ( End of ':'-definition ) 
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+ ADD 



4.8.8 



Plus 



Purpose: 
Category (+): 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Adds the top two 4-bit values and replaces them with the 4-bit 
result on top of the stack. 

Arithmetic/logical (single-length) 

(ADD): MARC4 mnemonic 

00 hex 

EXP ( n1 n2 -- n1+n2 ) 

RET ( - ) 

EXP: stack depth reduced by 1 , new top element 

RET: not affected 

CARRY flag Set on arithmetic overflow ( result > 15 ) 
BRANCH flag = CARRY flag 
Not affected 
1 

D+! 1+! 1-! -+! +C -C 
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+ ADD 

Example: 

VARIABLE Result 
: Single-addition 

5 3+ ( RPN addition: 5 + 3 := 8 ) 

Result ! ( Save result in memory ) 

3 Result +! ( Add 3 to memory location ) 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-39 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



+! 



4.8.9 



Plus-store 



Purpose: 



Category: 



Adds a 4-bit value to the contents of a 4-bit variable. On entry 
to the function, the TOS value is the 8-bit RAM address of the 
variable. 

Memory operation (single-length)/qFORTH macro 



Library Implementation: CODE +! Y! ( n addr -- n ) 

[Y]@ + (n-n @RAM[Y]-sum ) 
[Y]! ( sum - ) 

END-CODE 

The qFORTH compiler optimizes a word sequence such as 

"5 semaphore +!" into an instruction sequence of the 
following form : 

[>Y]@ semaphore 

ADD [Y]! 

EXP ( n RAM_addr - ) 
RET ( - ) 
EXP: 3 elements are popped from the stack 
RET: not affected 

CARRY flag: Set on arithmetic overflow ( result > 1 5 ) 
BRANCH flag = CARRY flag 
The contents of the Y or X register may be changed 
4 
+ ! 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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+! 

Example: 

VARIABLE Ramaddress 

: PLUS-STORE 

15 Ramaddress ! ( 15 is stored in the variable ) 

9 Ramaddress +! ( 9 is added to this variable ) 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-41 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.8.10 Plus-C 



+c 



ADDC 



Purpose: 

Category: 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



ADD with CARRY of the top two 4-bit values and replace 
them with the 4-bit result [n1 + n2 + CARRY] on top of the 
stack. 



arithmetic/logical (single-length) 
MARC4 mnemonic 



(+C): 
(ADDC) : 
01 hex 

EXP ( n1 n2 -- n1+n2+CARRY ) 
RET ( - ) 

EXP: 1 element is popped from the stack 
RET: not affected 

CARRY flag: Set on arithmetic overflow ( result > 15 ) 
BRANCH flag = CARRY flag 
Not affected 
1 

-C + DAA ADD 
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+c 



ADDC 



Examples: 

: Overflow 1 0 8 +C ; 



( -- 2 ; BRANCH, CARRY flag set 



: PLUS-C 



SET_BCF 4 3 +C 



( -- 8 ; flags : -— 



: D+ 



\ 8-bit addition using +C (d1 62 - d1+d2 



ROT + 
<ROT +C 
SWAP 



: ADDC-Example 

50 190 D+ (-- 240 = FOh ; no CARRY or BRANCH ) 

PLUS-C 

Overflow 

2DROP 2DROP ( the results. ) 
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4.8.11 Plus-LOOP 



+LOOP 



Purpose: 



Category: 

Library Implementation: 



+LOOP terminates a DO loop. Used inside a colon definition 
in the form DO ... n +LOOP. On each iteration of the DO loop, 
+LOOP increments the loop index by n. If the new index is 
incremented across the limit (>=), the loop is terminated and 
the loop control parameters are discarded. Otherwise, 
execution returns just after the corresponding DO. 

Control structure / qFORTH macro 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



CODE+LOOP 2R> 
ROT + OVER 
CMP_LT 
2>R 

(S)BRA _$DO 
_$LOOP: DROPR 
END-CODE 
EXP ( n -- ) 
IF Index+n < Limit 
THEN RET ( u| Limit | 
ELSE RET (u| Limit | 



( Move Limit & Index on EXP ) 



( Check for Index < Limit 



( Skip Limit & Index from RET ) 



Index 
Index 



u | Limit | Index+n ) 



EXP: top element is popped from the stack 

RET: top entry is popped from the stack, if +LOOP is 
terminated 

CARRY and BRANCH flags are affected 

Not affected 

10 

DO ?DO #DO #LOOP LOOP I J 7LEAVE -7LEAVE 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-44 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



+LOOP 

Example: 

: INCREMENT-COUNT 
10 0 DO 

I 

2 +LOOP ( NOTE: The BRANCH and CARRY flag are ) 

( altered during execution of +LOOP ) 
; ( EXP after execution: -- 0 2 4 6 8 ) 
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SUB 



4.8.12 Minus 



Purpose: 

Category: 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



2's complement subtract the top two 4-bit values and replace 
them with the result [n1 + /n2 + 1] on top of the stack 
(/n2 is the 1's complement of n2). 

(-) : arithmetic/logical (single-length) 

(SUB) : MARC4 mnemonic 

02 hex 

EXP ( n1 n2 ~ n1 + n2 + 1 ) 
RET ( - ) 

EXP: top element is popped from the stack 
RET: not affected 

CARRY flag: Set on arithmetic overflow (n1+/n2+1 > 15) 
BRANCH flag = CARRY flag 
Not affected 
1 

-C SUBB 
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SUB 

Example: 

: MINUS 5 3 - ( TOS = 2 ; flags : — ) 

: Underflow 35- ( TOS = E; BRANCH, CARRY flag set ) 
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-7LEAVE 



4.8.13 Not-Query-Leave 



Purpose: 



Conditional exit from within a LOOP structure if the previous 

tested condition was FALSE 

( ie. the BRANCH flag is RESET ). 

-7LEAVE is the opposite to 7LEAVE (condition TRUE). 

The standard FORTH word sequence NOT IF LEAVE 
THEN is equivalent to the q FORTH word -7LEAVE. 

-7LEAVE transfers control just beyond the next LOOP, 
+LOOP or #LOOP or any other loop structure like 
BEGIN ... UNTIL, WHILE 



Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Control structure/qFORTH macro 

CODE -7LEAVE TOG_BF ( Toggle BRANCH flag setting ) 

(S)BRA _$LOOP ( Exit LOOP if BRANCH flag set) 

END-CODE 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag: not affected 

BRANCH flag = NOT BRANCH flag 

Not affected 

3 

DO LOOP +LOOP #LOOP 7LEAVE 
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-7LEAVE 



Example: 

8 CONSTANT Length 

7 CONSTANT LSD 

Length ARRAY BCD_Number 



( 8 digit BCD value ) 



DIGIT+ 

Y! 

CLR_BCF 
#DO 

[Y]@ +C DAA 

[Y-]! 0 

-? LEAVE 

#LOOP 
DROP 



\ Add digit to n-digit BCD value 

( digit n LSD_Addr -- digit n 

( Clear BRANCH and CARRY flag 

( Use length as loop index 

( n -- m+n [BRANCH set on overflow] 

( m' -- 0 

( Finish loop, if NO overflow 
( Decrement index & repeat if >0 



: Add8 

BCD_Number Length ERASE ( clear the array ) 

8 Length BCD_Number [LSD] Digit+ 
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-c 



SUBB 



4.8.14 Minus-C 



Purpose: 

Category: 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



Subtract with BORROW [ = NO CARRY or /CARRY] 1 's 
complement of the top two 4-bit values and replace them with the 
4-bit result [ = n1+/n2+/CARRY ] on top of the stack (/n2 is the 
inverse bit pattern [1's complement] of n2). 

(-C) : arithmetic/logical (single-length) 

(SUBB) : MARC4 mnemonic 

03 hex 

EXP ( n1 n2 -- n1+/n2+/CARRY ) 
RET ( - ) 

EXP: top element is popped from the stack 
RET: not affect 

CARRY flag: Set on arithmetic underflow 
(n1+/n2+/CARRY> 15) 
BRANCH flag = CARRY flag 
Not affected 
1 

SUB TCS DAA - +C 
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-C SUBB 



Example: 

: DNEGATE \ Two's complement of top byte ( d1 -- -d1 ) 

0 - SWAP 

0 -C SWAP 
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0... Fh(15) LIT_0... LIT_F 



4.8.15 Literal 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



PUSH the LITeral <n> (0...15) onto the Expression 
Stack. 

Stack operation/assembler instruction 
60 ... 6F hex 

EXP(--n) <n = 0..Fh> 

RET ( - ) 

EXP: one element is pushed onto the stack. 

RET: not affected 

Not affected 

Not affected 

1 

CONSTANT 2CONSTANT 
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0... Fh(15) LIT_0... LIT_F 

Example: 



: LITERAL-example 

LIT_A ( is equivalent to A hex or 1 0 decimal ) 

LIT_0 ( is equivalent to 0 decimal ) 

+ ( results in the LIT_A remaining on the TOS ) 

DROP ( drop the result. ) 
( better used for above sequence : ) 
Ah 0 + DROP 

21hABh (-21-21 AB ) 

D+ 2DROP ( 2 1 A B - C C - ) 

12 1+ DROP (C-C1-D- ) 
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4.8.16 Zero-not-equal 



0<> 



Purpose: 



Category: 



Compares the 4-bit value on top of the stack to zero. 

If the value on the stack is not zero, then the BRANCH flag is 
set in the condition code register (CCR). This differs from 
standard FORTH, whereby a BOOLEAN value (0 or 1), 
depending on the comparison result, is pushed onto the 
stack. 

Comparison (single-length)/qFORTH macro 



Library Implementation: CODE 0<> 

OCMP NEDROP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 
EXP ( n - ) 
RET ( - ) 

EXP: top element is popped from the stack 

RET: not affected 

CARRY flag: affected 

BRANCH flag: set, if (TOS <> 0) 

Not affected 

3 

0= D0= DOo 
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0<> 

Example: 

: NOT-EQUALS-ZERO 

5 6 (-65 ) 

0<> (56 - 5; BRANCH flag SET ) 

DROP 0 (5-0 ) 

0= ( 0 - ; BRANCH flag SET ) 
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4.8.17 Zero-equal 



0= 



Purpose: 



Category: 



Compares the 4-bit value on top of the stack with zero. 

If the value of the stack is equal to zero, then the BRANCH 
flag is set in the condition code register. This differs from 
standard FORTH, whereby a BOOLEAN value (0 or 1), 
depending on the comparison result, is pushed onto the 
stack. 

Comparison (single-length)/qFORTH macro 



Library Implementation: CODE 0= 

0 CMP_EQ DROP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 
EXP ( n - ) 
RET ( - ) 

EXP: top element is popped from the stack 

RET: not affected 

CARRY flag: affected 

BRANCH flag: set, if (TOS = 0) 

Not affected 

3 

D0= D0<> 0<> 
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Example: 



0= 



ZERO-EQUALS 
56 

0<> 

DROP0 
0= 



(-65 ) 

(56-5; BRANCH flag SET ) 

(5-0 ) 

( 0 - ; BRANCH flag SET ) 
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1 + 



INC 



4.8.18 One-plus 



Purpose: 
Category: 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Increments the 4-bit value on top of the stack (TOS) by 1 . 
(1+): Arithmetic/logical (single-length) 
(INC): MARC4 mnemonic 
14 hex 

EXP ( n -- n+1 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag: not affected 

BRANCH flag: set, if (TOS = 0) 

Not affected 

1 

1- 1+! 
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1 + 



INC 



Example: 



VARIABLE PresetValue 



VARIABLE Switch 



: DownCounter 



( PresetValue -- 
( n -- n-1 



BEGIN 1- 



UNTIL DROP 



: UpCounter 



( PresetValue -- 
( n -- n+1 



BEGIN 1 + 



UNTIL DROP 

> 

: SelectDirection 

9 PresetValue ! 
0 Switch ! 
BEGIN 

PresetValue @ 

Switch 1 TOGGLE ( Toggle between 1 <-> 0) 

IF DownCounter 
ELSE UpCounter 
THEN 

PresetValue 1-! 
UNTIL 



MARC4 4-bit Microcontrollers Programmer's Guide 



ill nEL 

^^^^^^^ 




4-59 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



1+! 



4.8.19 One-plus-store 



Purpose: 
Category: 

Library Implementation: 

Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 



Bytes Used: 
See Also: 



Increments the 4-bit contents of a specified memory 
location. 1+! requires the address of the variable on top 
of the stack. 

Memory operation (single-length)/qFORTH macro 
CODE 1+! 

Y! [Y]@ 1+ [Y]! ( increment variable by 1 ) 
END-CODE 
EXP ( addr ~ ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 

RET: not affected 

CARRY flag: not affected 

BRANCH flag: set, if (TOS = 0) 

The address is stored into the Y or X register, then the 
value is fetched from RAM, the value is incremented on 
the stack and restored in the address indicated by the Y 
(or X) register. 

4 

+! 1-! 
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1+! 

Example: 

VARIABLE State 
: StateCounter 

5 State ! ( store 5 in the memory location ) 

6 0 DO ( set loop index = 6 ) 

State 1 +! ( increment contents of variable 'State') 

LOOP 
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1- 



DEC 



4.8.20 One-minus 



Purpose: 
Category (1-): 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Decrements the 4-bit value on top of the stack (TOS) 
by 1. 

Arithmetic/logical (single-length) 
(DEC): MARC4 mnemonic 
15 hex 

EXP ( n -- n-1 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag not affected 

BRANCH flag Set, if (TOS = 0) 

Not affected 

1 

1+ 1-! 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-62 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



1- 



DEC 



Example: 



VARIABLE PresetValue 



VARIABLE Switch 



: DownCounter 



( PresetValue -- 
( n -- n-1 



BEGIN 1- 



UNTIL DROP 



: UpCounter 



( PresetValue -- 
( n -- n+1 



BEGIN 1 + 



UNTIL DROP 

> 

: SelectDirection 

9 PresetValue ! 
0 Switch ! 
BEGIN 

PresetValue @ 

Switch 1 TOGGLE ( Toggle between 1 <-> 0) 
IF DownCounter 
ELSE UpCounter 
THEN 



PresetValue 1-! 



( UNTIL PresetValue = 0 ) 



UNTIL 
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1-! 



4.8.21 One-minus-store 



Purpose: 



Decrements the 4-bit contents of a specified memory 
location. 1-! requires the address of the variable on top of the 
stack. 



Category: Memory operation (single-length)/qFORTH macro 

Library Implementation: CODE 1-! 

Y! [Y] @ 1 - [Y]! ( decrement variable by 1 ) 

END-CODE 
Stack Effect: EXP ( addr » ) 

RET ( - ) 

Stack Changes: EXP: 2 elements are popped from the stack 

RET: not affected 
Flags: CARRY flag: not affected 

BRANCH flag: set, if (TOS = 0) 



X Y Registers: 



Bytes Used: 
See Also: 



The address is stored into the Y (or X) register, then the value 
is fetched from RAM, the value is decremented on the stack 
and re-stored in the address indicated by the Y (or X) 
register 

4 

+! 1+! ! 
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Example: 



1-! 



VARIABLE PresetValue 
VARIABLE Switch 

: DownCounter ( PresetValue -- ) 

BEGIN 1- UNTIL DROP; ( n -- n-1 ) 

: UpCounter ( PresetValue -- ) 

BEGIN 1+ UNTIL DROP ; ( n -- n+1 ) 
: SelectDirection 

9 PresetValue ! 

0 Switch ! 

BEGIN 

PresetValue @ 

Switch 1 TOGGLE ( Toggle between 1 <-> 0 ) 

IF DownCounter ELSE UpCounter THEN 
PresetValue 1-! ( UNTIL PresetValue = 0 ) 

UNTIL 
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2! 



4.8.22 Two-store 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Stores the 8-bit value on TOS into an 8-bit variable in 
RAM. The address of the variable is the TOS value. 

Arithmetic/logical (double-length)/qFORTH macro 



CODE 2! 



( nh nl addr - nh nl ) 



( nh nl 
( nl nh 
(nl- 

■) 



nl nh 
nl 



Y! 

SWAP 
[Y]! 
[+Y]I 

END-CODE 

EXP ( n_h nj RAM_addr 
RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 
not affected 

The contents of the Y or X register may be changed 
4 

2@ D+! D-! 
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2! 

Example 1 : 

: D-STORE 

1 3h 43h 2! ( RAM [43] = 1 ; RAM [44] = 3 ) 

; ( but normally variable names are used ! ) 



Example 2: 

2VARIABLE Counter 
: DoubleCount 

0 0 Counter 2! ( initialize the 8-bit counter ) 

BEGIN 

0 1 Counter D+! ( increment the 8-bit counter ) 

Counter 2@ 20h D= ( until 20h is reached ... ) 
UNTIL 
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4.8.23 Two-multiply 



Purpose: 



SHL 



Multiplies the 4-bit value on top of the stack by 2. SHL 
shifts TOS left into CARRY flag. 



TOS 



3 


2 


1 


0 



Category: 

MARC4 Opcode: 
Library Implementation: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



(2*) : Arithmetic/logical (single-length)/qFORTH macro 
(SHL) : MARC4 mnemonic/assembler instruction 
10 hex (SHL) 

CODE 2* SHL END-CODE 

EXP ( n -- n*2 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag: MSB of TOS is shifted into CARRY 
BRANCH flag = CARRY flag 
Not affected 
1 

ROL ROR SHR 21 D2* D2/ 
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SHlJ 



Example 1 : 

: MULT-BY-TWO 

7 2* 

18h SHLSWAP 
ROL SWAP 

Example 2: 



( multiply a 4-bit number: 
( 7h - Eh 

( multiply a 8-bit number: 'D2*' Macro 
( 18h -0 1h [CARRY flag set] 
( 0 1 h [CARRY] - 30h 
( 18h *2 = 30h ! use 'D2*' ! 



BitShift 
SET_BCF 3 
ROR DROP 
CLR_BCF 3 
ROR DROP 
SET_BCF 3 
ROL DROP 
CLR_BCF 3 
ROL DROP 



(3 = 0011b 

( [CARRY] 3 - [CARRY] 9 = 1001b 
(3 = 0011b 

( [no CARRY] 3 -- [CARRY] 1 = 0001b 
(3 = 0011b 

( [CARRY] 3 -- [no CARRY] 7 = 01 1 1 b 
(3 = 0011b 

( [no CARRY] 3 -- [no CARRY] 6 = 01 1 0b 



CLR_BCF Fh 
21 DROP 



(-SHR-[no CARRY] F - [CARRY] 7 = 01 1 1 b ) 



CLR_BCF 6 
2* DROP 



(6 = 0110b ) 
(- SHL - [no CARRY] 6 -- [no C] C = 1 1 00b) 
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4.8.24 Two-divide 



21 



Purpose: 



SHR 



Divides the 4-bit value on top of the stack by 2. SHR 
shifts the TOS right into the CARRY flag. 



TOS 



0 


— > 


3 


2 


1 


0 




C 



Category: 

MARC4 Opcode: 
Library Implementation: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



(2/) : arithmetic/logical (single-length)/qFORTH macro 
(SHR) : MARC4 mnemonic/assembler instruction 
12 hex (SHR) 

CODE 21 SHR END-CODE 

EXP ( n -- n/2 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag: LSB of TOS is shifted into CARRY 
BRANCH flag = CARRY flag 
Not affected 
1 

2* SHL D2* D2/ ROR ROL 
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21 SHR 

Example: 

: TWO-DIVIDE 

10 2/ (10 --5 ) 

( divide an 8-bit number: 'D2/' Macro : ) 
30h SWAP SHR ( 30h - 0 1 h [CARRY flag set] ) 

SWAP ROR ( 0 1 [CARRY] - 18h ) 

; ( 30h/2 = 18h ! use 'D2/' ! ) 

For another example see '2*', 'SHU. 
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2<R0T 



4.8.25 Two-left-rote 



Purpose: 
Category: 

Library Implementation: 



Moves the top 8-bit value to the third byte position on the 
EXP stack, i.e., performs an 8-bit left rotate. 

Stack operation (double-length)/qFORTH colon definition 

: 2<ROT 

ROT >R ( d1 d2 d3 — d1 d2h d3 

ROT >R ( d1 d2h d3 — d1 d3 

ROT >R (d1d3 — d1hd3 

ROT R> (d1hd3 — d3d1 

R> R> ( d3 d1 — d3 d1 d2 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 d3 -- d3 d1 d2 ) 
RET ( - ) 

EXP: affected ( changed order of elements ) 
RET: use of 3 RET levels in between 
Not affected 
Not affected 
14 

ROT <ROT 2ROT 
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2<R0T 

Example: 

: TWO-LEFT-ROT 

1 1 h 22h 33h ( — 1 1 h 22h 33h ) 

2<ROT ( 1 1 h 22h 33h -- 33h 1 1 h 22h ) 

ROT ( 33h 1 1 h 22h -- 33h 12h 21 h ) 
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2>R 



4.8.26 Two-to-R 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Moves the top two 4-bit values from the Expression Stack 
and pushes them onto the top of the return stack. 

2>R pops the EXP stack onto the RET stack. To avoid 
corrupting the RET stack and crashing the system, each use 
of 2>R MUST be followed by a subsequent 2R> (or an 
equivalent 2R@ and DROPR) within the same colon 
definition. 

Stack operation (double-length)/assembler instruction 
28 hex 

EXP ( n1 n2 -- ) 
RET(-u| n2 1 n1 ) 

EXP: 2 elements are popped from the stack 
RET: 1 ( 8-bit ) entry is pushed onto the stack 
Not affected 
Not affected 
1 

I >R R> 2R@ 2R> 3R@ 3>R 3R> 
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2>R 

Example: 



: 2SWAP ( Swap 2nd byte with top ) 

>R <ROT ( d1 d2 -- n2_h d1 ) 

R> <ROT ( n2_h d1 -- d2 d1 ) 

: 20VER ( Duplicate 2nd byte onto top) 

2>R ( d1 d2 -- d1 ) 

2DUP (d1--d1d1 ) 

2R> (d1d1-d1d1d2 ) 

2SWAP ( d1 d1 d2 -- d1 d2 d1 ) 
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4.8.27 Two-fetch 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Copies the 8-bit value of a 2VARIABLE or 2ARRAY 
element to the stack. The MSN address of the selected 
variable is the TOS value. 

Arithmetic/logical (double-length)/qFORTH macro 

CODE 2@ Y! (addr- ) 

[Y]@ ( - nh ) 

[+Y]@ (nh-nhnl ) 

END-CODE 

EXP ( RAM_addr - n_h n_l ) 
RET ( - ) 

EXP: The top two elements will be changed 
RET: not affected 
not affected 

The contents of the Y or X register may be changed 
3 

Other byte (double-length) qFORTH dictionary words, 
like 

D- D+ 2! D+! D-! D2/ D2* D< D> Do D= D<= D>= 
D0= DOo 
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2@ 

Example 1 : 

: StoreFetch 

1 3h 43h 2! ( RAM [43] = 1 ; RAM [44] = 3 ) 

( use var name instead of address ) 
43h 2@ (--13 ) 

2DR0P 



Example 2: 

2VARIABLE Counter 

: DoubleCount 

0 0 Counter 2! 
BEGIN 

0 1 Counter D+! 

Counter 2 @ 20h D= 
UNTIL 



( initialize the 8-bit counter ) 

( increment the 8-bit counter ) 
( until 20h is reached ... ) 
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2 ARRAY 



4.8.28 two-array 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Allocates RAM memory for storage of a short double-length 
(8-bit/byte) array, using a 4-bit array index value. Therefore, 
the number of 8-bit array elements is limited to 16. 

The qFORTH syntax is as follows: 

<number> 2ARRAY <identifier> [ AT <RAM-Addr> ] 

At the time of compilation, 2ARRAY adds <identifier> to the 
dictionary and ALLOTs memory for storage of <number> 
double-length values. At execution time, <identifier> leaves 
the RAM start address of the parameter field (<identifier> [0]) 
on the Expression Stack. 

The storage area allocated by 2ARRAY is not initialized. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

ARRAY LARRAY 2LARRAY 2VARIABLE VARIABLE 
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Example: 



2 ARRAY 



6 2ARRAY RawData 
3 CONSTANT STEP 
: lnit_RawData 
15h 6 0 DO 

2DUP 

I RawData INDEX 2! 
STEP Ni- 
l-OOP 

2DROP 



( RawData[0] ... RawData[5] ) 



( RawData[0] 
( RawData[1 ] 
( RawData[2] 
( RawData[3] 
( RawData[4] 
( RawData[5] 



15h 
12h 
OFh 
OCh 
09h 
06h 



: Setup_RAM 
lnit_RawData 
RawData [3] 2@ 
Oh D+ 
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4.8.29 two-constant 



2CONSTANT 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Creates a double-length (8-bit) constant definition. The 
qFORTH syntax is as follows: 

<byte_constant> 2CONSTANT <identifier> 

which assigns the 8-bit value <byte_constant> to <identifier>. 

Predefined data structure 

EXP ( - d ) at execution time 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

ARRAY, CONSTANT 
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2C0NSTANT 



Example: 



OOh 2CONSTANT ZEROb 
01 h 2CONSTANT ONEb 
: Emit_HexByte 

2DUP 3 OUT 

SWAP 2 OUT 

SWAP 



( define byte constants 



) 



\ Emit routine EXP: ( n1 n2 -- ) 
( Duplicate & emit lower nibble) 



: FIBONACCI 
ZEROb ONEb 
12 0 DO 

Emit_HexByte 
2SWAP 20VER 
D+ 
LOOP 

Emit_HexByte 

2DROP 2DROP 



Display 12 FIBONACCI nrs. 
Set up for calculations 
Set up loop -- 12 numbers 
Emit top 8-bit number 
Switch for addition 
Add top two 8-bit numbers 
Go back for next number 
Emit last number too 
Clean up the stack 
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4.8.30 Two-DROP 



2DROP 



Purpose: 



Removes one double-length (8-bit) value or two single-length 
(4-bit) values from the Expression Stack. 



Category: Stack operation (double-length)/qFORTH macro 

Library Implementation: CODE 2DROP 

DROP DROP 
END-CODE 
EXP ( n1 n2 -- ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 
RET: not affected 
Not affected 
Not affected 
2 

DROP 3DROP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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Example: 



2DR0P 



TWO-DROP 
19H 1 1 H 
2DROP 



( Simple example for 2DR0P ) 
( ~19h11h ) 
( 19h 11h ~ 19h ) 
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4.8.31 Two-doop 



2DUP 



Purpose: 



Duplicates the double-length (8-bit) value on top of the 
Expression Stack. 



Category: Stack operation (double-length)/qFORTH macro 

Library Implementation: CODE 2DUP 

OVER OVER 
END-CODE 
EXP ( d - d d ) 
RET ( - ) 

EXP: top 2 elements are pushed again onto the stack 
RET: not affected 
Not affected 
Not affected 
2 

DUP3DUP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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Example: 



2DUP 



2VARIABLE CounterValue 
: Update_Byte 
2DUP 

2@ 2SWAP 
18 2SWAP 
D+! 



( 8-bit counter value 
( addr -- current value 
( addr -- addr addr 
( addr addr -- d addr 
( d addr --d 18 addr 
(d 18 addr-- d 



: Task_5 

CounterValue Update_Byte ( -- d ) 
3 OUT 2 OUT 
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4.8.32 Two-long-ARRAY 



2LARRAY 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Allocates RAM space for storage of a double-length 
(8-bit) long array which has an 8-bit index to access the 
8-bit array elements (more than 16 elements). 

The qFORTH syntax is as follows 

<number> 2LARRAY <identifier> 
[ AT <RAM address> ] 

At the time of compilation, 2LARRAY adds <identifier> to 
the dictionary and ALLOTs memory for storage of 
<number> double-length values. At execution time, 
<identifier> leaves the RAM start address of the array 
(<identifier> [0]) on the Expression Stack. The storage 
area ALLOTed by 2LARRAY is not initialized. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

ARRAY 2ARRAY LARRAY 
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2 LA R RAY 

Example: 

25 2LARRAY VarText 

20 2CONSTANT StrLength 

ROMCONST FixedText StrLength, " Long string example " , 



: TD- D- IF ROT 1- <ROT THEN ; 
: TD+ D+ IF ROT 1+ <ROT THEN ; 
: ROM_Byte@ 
3>R 3R@ TABLE ;; 

: CopyString 
FixedText ROM_Byte@ 
2>R 

2R@ TD+ 
BEGIN 

ROM_Byte@ 

2R> 1 M-2>R 

2R@ VarText INDEX 2! 

0 1 TD- 

2R@ D0= 
UNTIL 

DROPR 3DROP 



subtract 8 from 12-bit. 
add 8-bit to a 12-bit value. 

keep ROMaddr on EXP; fetch char. 

copy string from ROM into RAM array 
get string length. 

move length/index to return stack 
length + start addr=ROMaddr [lastchar] 

get ASCII char 
index := index - 1 
store char in array. 
ROMaddr := ROMaddr - 1 
index = 0 ? 

skip count & ROMaddr. 
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2NIP 



4.8.33 Two-NIP 



Purpose: 



Removes the second double-length (8-bit) value from the 
Expression Stack. 



Category: Stack operation (double-length)/qFORTH macro 

Library Implementation: CODE 2NIP 

ROT DROP 
ROT DROP 
END-CODE 
EXP ( d1 d2 -- d2 ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 
RET: not affected 
Not affected 
Not affected 
4 

NIP SWAP DROP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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2NIP 

Example: 

: Cancel-2nd-Byte 

9 25 5Ah ( -9 19h5Ah ) 

2NIP ( 9 19h 5Ah -- 9 5Ah) 
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4.8.34 Two-OVER 



20VER 



Purpose: 
Category: 

Library Implementation: 



Copies the second double-length (8-bit) value onto the top 
of the Expression Stack. 

Stack operation (double-length)/qFORTH colon definition 
: 20VER 

2>R (d1d2~d1 ) 

2DUP (d1~d1d1 ) 

2R> (d1d1~d1d1d2 ) 

2SWAP ( d1 d1 d2 -- d1 d2 d1 ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 -- d1 d2 d1 ) 
RET ( - ) 

EXP: 2 elements are pushed onto the stack 

RET: 3 levels are used in between 

Not affected 

Not affected 

8 

2DUP 2SWAP OVER 
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20VER 

Example: 

: Double-2nd-Byte 

12H 19H ( -- 12h 19h ) 

20VER ( 12h 19h -- 12h 19h 12h ) 
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2R> 



4.8.35 Two-R-from 



Purpose: 



Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Moves the double-length (8-bit) value from the Return 
Stack onto the Expression Stack. 2R@, 2R> and 2>R 
allow use of the Return Stack as a temporary storage for 
8-bit values. 

2R> removes elements from the Return Stack onto the 
Expression Stack. To avoid corrupting the Return Stack 
and crashing the program, each use of 2R> MUST be 
preceded by a 2>R within the same colon definition. 

Stack operation (double-length)/qFORTH macro 

CODE 2R> 

2R@ DROPR 

END-CODE 

EXP ( - n1 n2 ) 

RET(uln2ln1~ ) 

EXP: 2 elements are pushed onto the stack 
RET: 1 ( 8-bit ) entry is popped from the stack 
Not affected 
Not affected 
2 

l>RR> 2R@ 2>R 3R@3>R3R> 
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Example 1 : 



Library implementation: of +LOOP: 



2R> 



CODE +LOOP 
2R> 

ROT + OVER 

CMP_LT 

2>R 

(S)BRA _$DO 
_$LOOP: DROPR 
END-CODE 



( Move limit & index on EXP ) 



( Check for index < limit 



( Skip limit & index from RET ) 



Example 2: 



20VER 
2>R 
2DUP 
2R> 
2SWAP 



( Duplicate 2nd byte onto top 

(d1 d2 -d1 

(d1 -d1 d1 

(d1 d1 --d1 d1 d2 

(d1 d1 d2 --d1 d2d1 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-93 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



2R@ 



4.8.36 Two-R-fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Takes a copy of the 8-bit value on top of the Return Stack 
and pushes the double-length (8-bit) value on the Expression 
Stack. 

2R@, 2R> and 2>R allow use of the Return Stack as a 
temporary storage for 8-bit values. 

Stack operation (double-length)/assembler instruction 

2A hex 

EXP ( -- n1 n2 ) 

RET ( uln1ln2 -- uln1ln2 ) 

EXP: 2 elements are pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

1 

I >R R> 2>R 2R> 3R@ 3>R 3R> 
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2R@ 

Example: 

: 20VER ( Duplicate 2nd byte onto top ) 

2>R ( d1 d2 -- d1 ) 

2DUP (d1-d1d1 ) 

2R@ DROPR ( d1 d1 -- d1 d1 d2 ) 

2SWAP ( d1 d1 d2 -- d1 d2 d1 ) 
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2R0T 



4.8.37 Two-rote 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Moves the third double-length (8-bit) value onto the top of the 
Expression Stack. 

Stack operation (double-length)/qFORTH macro definition 

CODE 2ROT 

2>R 2SWAP ( d1 d2 d3 - d2 d1 ) 

2R> 2SWAP ( d2 d1 - d2 d3 d1 ) 

END-CODE 

EXP ( d1 d2 d3 — d2 d3 d1 ) 

RET ( - ) 

EXP: affected ( changes order of elements ) 
RET: affected (3 levels are used in between) 
Not affected 
Not affected 
5-7 

2<ROT <ROT ROT 
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2 ROT 

Example: 

: Rotate-Byte-to-Top 

1 1 h 22h 33h ( — 1 1 h 22h 33h ) 

2R0T ( 1 1 h 22h 33h - 22h 33h 1 1 h ) 
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4.8.38 Two-SWAP 



2SWAP 



Purpose: 



Exchanges the top two double-length (8-bit) values on the 
Expression Stack. 



Category: Stack operation (double-length)/qFORTH colon definition 

Library Implementation: : 2SWAP 

>R <ROT ( d1 d2 -- d2h d1 ) 
R> <ROT ( d2h d1 -- d2 d1 ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 -- d2 d1 ) 
RET ( - ) 

EXP: affected ( changes order of elements ) 
RET: affected (1 level is used intermediately) 
Not affected 
Not affected 
8 

SWAP 
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2SWAP 

Example: 

: Swap-Bytes 

3 12h19h (~3 12h19h ) 

2SWAP ( 3 12h 19h --3 19h 12h) 
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2TUCK 



4.8.39 Two-TUCK 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Tucks the top 8-bit (double-length) value under the 
second byte on the Expression Stack, the counterpart to 
20VER. 

Stack operation (double-length)/qFORTH colon definition 
: 2TUCK 

3>R ( n1 n2 n3 n4 - n1 

2R@ ( n1 - n1 n3 n4 

ROT ( n1 n3 n4 - n3 n4 n1 

3R> ( n3 n4 n1 - n3 n4 n1 n2 n3 n4 

; ( n3 n4 n1 n2 n3 n4 - d2 d1 d2 

EXP ( d1 d2 -- d2 d1 d2 ) 
RET ( - ) 

EXP: Two 4-bit elements are pushed under the 2nd byte 

RET: affected ( 1 level is used intermediately ) 

Not affected 

Not affected 

6 

TUCK 20VER 
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2TUCK 

Example: 

: Tuck-under-2nd-Byte 

11H22H (~11h22h ) 

2TUCK ( 11h22h--22h 11h22h ) 
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2VARIABLE 



4.8.40 two-variable 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Allocates RAM space for storage of one double-length (8-bit) 
value. 

The qFORTH syntax is as follows 

2VARIABLE <name> [ AT <address.> ] 
[ <number> ALLOT ] 

At the time of compilation, 2VARIABLE adds <name> to the 
dictionary and ALLOTs memory for storage of one 
double-length value. If AT <address> is appended, the 
variable/s will be placed at a specific address ( i.e.: 'AT 40h' ). 
If <number> ALLOT is appended, a total of 2 * 
(<number> +1) 4-bit memory locations will be allocated. At 
execution time, <name> leaves the start address of the 
parameter field on the Expression Stack. 

The storage area allocated by 2VARIABLE is not initialized. 

Predefined data structure 

EXP ( - d ) at execution time 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

ALLOT VARIABLE 2ARRAY ARRAY 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-102 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



2VARIABLE 

Example: 



2VARIABLE NoKeyCounter 
: No_KeyPressed 

0 0 NoKeyCounter 2! 

NoKeyCounter 2 @ 1 M+ 

IF NoKeyOverTHEN 

NoKeyCounter 2! 



( 8-bit variable ) 

( initialise to $00 ) 
( increment by 1 ) 
( 'call' NoKeyOver on overflow) 
( store the result back ) 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-103 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.8.41 Three-store 



3! 



Purpose: 
Category: 

Library Implementation: 



Store the top 3 nibbles into a 12-bit variable in RAM. The 
most significant digit address of that array has to be the TOS 
value. 

Memory operation (triple-length)/qFORTH colon definition 



:3! 



Y! 

SWAP ROT 
[Y]l [+Y]I 
[+Y]I 



( nh nm nl addr -- nh nm nl) 
( nh nm nl -- nl nm nh ) 



( nl nm nh 
(nl- 



nl 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( nh nm nl addr -- ) 

RET ( - ) 

EXP: 5 elements are popped from the stack 

RET: not affected 

Not affected 

The contents of the Y register will be changed 
7 

3@ T+! T-! TD+! TD-! 
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Example: 

3 ARRAY 3Nibbles AT 40h ( 3 nibbles at fixed locations. ) 
: Triples 

123h 3Nibbles 3! ( store 123h in the 3 nibbles array. ) 

321h3Nibbles T+! ( 123h + 321 h = 444h ) 

3Nibbles 3@ 3DROP ( fetch the result onto expression stack ) 

123h3Nibbles T-! ( 444h - 123h = 321 h ) 
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3>R 



4.8.42 Three-to-R 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Removes the top 3 values from the Expression Stack and 
places them onto the Return Stack. 3>R unloads the EXP 
stack onto the RET stack. To avoid corrupting the RET stack 
and crashing the system, each use of 3>R MUST be followed 
by a subsequent 3R> within the same colon definition. 

Stack operation (triple-length)/assembler instruction 

29 hex 

EXP ( n1 n2 n3 --) 

RET ( - n3 1 n2 | n1) 

EXP: 3 elements are popped from the top of the stack 
RET: 1 entry ( 3 elements ) is pushed onto the stack 
Not affected 
Not affected 
1 

I >R R> 2R@ 2>R 2R> 3R@ 3R> 
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3>R 

Example: 



2TUCK 


\ TUCK top 8-bit value under the 2nd byte 


3>R 


( n1 n2 n3 n4 -- n1 ) 


2R@ 


( n1 - n1 n3 n4 ) 


ROT 


( n1 n3 n4 -- n3 n4 n1 ) 


3R> 


( n3 n4 n1 -- n3 n4 n1 n2 n3 n4 ) 




( d1 d2 -- d2 d1 d2 ) 
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\3@ 



4.8.43 Three-fetch 



Purpose: 



Category: 



Fetch a 12-bit variable in RAM and push it on the Expression 
Stack. The most significant digit address of the variable must 
be on the TOS. 

Memory operation (triple-length)/qFORTH macro 



Library Implementation: CODE 3@ Y! 

[Y]@ 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



( addr - ) 
( - nh ) 
[+Y]@ (nh-nhnm ) 
[+Y]@ ( nh nm -- nh nm nl ) 

END-CODE 

EXP ( addr - nh nm nl ) 
RET ( - ) 

EXP: 2 elements are popped from and 3 are pushed onto 
the expression stack. 

RET: not affected 

Not affected 

The contents of the Y or X register may be changed 
5 

3! T+! T-! 
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Example: 



3@ 



3 ARRAY 3Nibbles AT 40h 



( 3 nibbles at fixed locations in RAM ) 



Triples 

123h3Nibbles 3! 
321h3Nibbles T+! 
3Nibbles3@ 3DROP 
123h3Nibbles T-! 
3Nibbles3@ 3DROP 



( store 123h in the 3 nibbles array. 

( 123h + 321h = 444h 

( fetch the result onto expression stack. 

( 444h - 123h = 321 h 

( fetch the result onto expression stack. 
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4.8.44 Three-DROP 



3DROP 



Purpose: 



Removes one 1 2-bit or three 4-bit values from the Expression 
Stack. 



Category: Stack operation (triple-length)/qFORTH macro 

Library Implementation: CODE 3DROP 

DROP DROP DROP 
END-CODE 
EXP ( n1 n2 n3 -- ) 
RET ( - ) 

EXP: 3 elements are popped from the stack 
RET: not affected 
Not affected 
Not affected 
3 

DROP 2DROP DROPR 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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3DR0P 

Example: 

: Skip-top-3-nibbles 

3467 (--3467 ) 

3DR0P ( 3 4 6 7 -- 3 ) 
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3DUP 



4.8.45 Three-doop 



Purpose: 



Duplicates the 12-bit address value on top of the Expression 
Stack. 



Category: Stack operation (triple-length)/qFORTH colon definition 

Library Implementation: CODE 3DUP 

3>R3R@3R> (t~tt) 

END-CODE 

EXP ( n1 n2 n3 -- n1 n2 n3 n1 n2 n3 ) 

RET ( - ) 

EXP: 3 elements are pushed onto the stack 
RET: affected (1 level is used intermediately) 
Not affected 
Not affected 
4 

DUP2DUP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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3DUP 

Example: 

ROMCONST Message 5 , " Error " , 
: Duplicate-ROMaddr 

Message 3DUP ( duplicate ROM address on stack ) 

ROMByte® ( fetch string length ) 

NIP ( get string length as 4-bit value ) 
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3R> 



4.8.46 Three-R-from 



Purpose: Moves the top 3 nibbles from the Return Stack and puts them 

onto the Expression Stack. 3R> unloads the Return Stack 
onto the Expression Stack. To avoid corrupting the Return 
Stack and crashing the system, each use of 3R> MUST be 
preceded by a 3>R within the same colon definition. 

Category: Stack operation (triple-length)/qFORTH macro 

Library Implementation: CODE 3R> 

3R@ 
DROPR 

END-CODE 
EXP ( -- n1 n2 n3 ) 
RET ( n3 1 n2 1 n1 --) 
EXP: 3 elements are pushed onto the stack 
RET: 1 element (3 nibbles) is popped from the stack 
Not affected 
Not affected 
2 

I >R R> 2R@ 2>R 2R> 3R@ 3>R 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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Example: 



3R> 



CODE 3DUP 

3>R 

3R@ 

3R> 
END-CODE 

ROMCONST StringExample 6 
: Duplicate-ROMAddr 

StringExample 3DUP 

0 DTABLE® 

NIP 



( Library implementation: of 3DUP 

(t- 

(~t 

(t-tt 



String " , 



( duplicate ROM address on stack 
( fetch 1st value of ROM string 
( get string length as 4-bit value 
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4.8.47 Three-R-fetch 



3R@ 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Copies the top 3 values from the Return Stack and leaves the 
3 values on the Expression Stack. 3R@ fetches the topmost 
value on the Return Stack. 3R@, 3R> and 3>R allow use of 
the Return Stack as a temporary storage for values within a 
colon definition. 

Stack operation (triple-length)/assembler instruction 
2B hex 

EXP ( -- n1 n2 n3 ) 
RET ( n3 1 n2 1 n1 -- n3 1 n2 1 n1) 
EXP: 3 elements are pushed onto the stack 
RET: not affected 
Not affected 
Not affected 



1 

I >R R> 2R0 



2>R 2R> -3>R 3R> 
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Example 1 : 

CODE 3DUP ( Library implementation: of 3DUP ) 

3>R ( t - ) 

3R@ (~t ) 

3R> ( t -- 1 1 ) 

END-CODE 



3R@ 



Example 2: 

: ROM_Byte@ ( ROM_addr -- ROM_addr ROM_byte ) 

3>R ( ROM_addr -- ) 

3R@ ( -- ROM_addr ) 

TABLE ( ROM_addr -- ROM_addr ROM_byte ) 

;; ( back to 'CALL', implicite EXIT ) 
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4.8.48 Colon 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Begins compilation of a new colon definition, i.e. defines the 
entry point of a new subroutine. Used in the form 

: <name> ... <words> ... ; 

":" creates a new dictionary entry for <name> and compiles 
the sequence between <name> and ";" into this new 
definition. If no errors are encountered during compilation, 
the new colon definition may itself be used in subsequent 
colon definitions. 

On execution of a colon definition, the current program 
counter is pushed onto the Return Stack. 

Predefined data structure 



EXP 
RET 
EXP: 
RET: 

Not affected 
Not affected 
0 

; INTO .. INT7 



(--) 

( -- ReturnAddress) 
not affected 

The return address to the word which 
executes this colon definition is pushed onto 
the stack 
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Example: 



COLON-Example 
3 BEGIN 

1+ DUP9 
UNTIL 



( BEGIN a colon definition 

( 3 = initial start value 

( increment count 3 -> 9 

( continue until condition is true 

( END of DEFINITION with a SEMICOLON 
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4.8.49 Semicolon 



EXIT RTI 



Purpose: 



Category: 

MARC4 Opcode: 
Stack Effect: 

Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Terminates a qFORTH colon definition, i.e. exits the current 
colon definition. 

";" compiles to EXIT at the end of a normal colon definition. It 
then marks the new definition as having been successfully 
compiled so that it can be found in the dictionary. 

";" compiles to RTI at the end of an INTO .. INT7 or $RESET 
definition. 

When EXIT is executed, program control passes out of the 
current definition. EXIT may NOT be used inside any iterative 
DO loop structure, but it may be used in control structures, 
such as: 

BEGIN ... WHILE, REPEAT, ... UNTIL, ... AGAIN, and 

IF ... [ ELSE ... ] THEN 
(;) : Predefined data structure 
(RTI/EXIT): MARC4 mnemonic 
EXIT: 25 hex RTI : 1 D hex 
EXP ( -) 

RET ( Return address --) 

EXP: not affected 



RET: 



The address on top of the stack is moved 
into the PC 



CARRY and BRANCH flags are not affected 

Not affected 

1 

: 7LEAVE -7LEAVE ;; 
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EXIT RTI 



Example: 

: Colon-Def 

3 BEGIN ( 3 is the initial start value ) 

1+DUP9= ( increment count from 3 -> 9 ) 

UNTIL ( Repeat UNTIL condition is TRUE ) 

; ( EXIT from the colon def. with ';' ) 

: INT5 ( Register contents saved automatically. ) 

Dl ( disable Interrupts ) 

Colon-Def ( execute 'colon def ) 
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J J 



4.8.50 Double-Semicolon Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Suppresses the code generation of an EXIT or RTI at the end 
of a colon definition. This function is typically used after any 
TABLE instruction (see ROMByte®, DTABLE®), in C 
computed goto jump tables (see EXECUTE) or in the 
$AUTOSLEEP definition. 

Predefined data structure 



EXP 
RET 
EXP: 
RET: 



(--) 
(") 

not affected 
not affected 



Not affected 
Not affected 
0 

: ; $AUTOSLEEP, ROMByte^ 



DTABLE « 
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■ ■ 

J J 

Example: 

: Dojncr 

DROPR \ Skip Return address 

Time_count 1*! 
[N]; 



: Do_Decr 

DROPR 

Time_count 1-! 

[N]; 



: Do_Reset 

DROPR 

0 Time_Count ! 

[N]; 



Jump_Table 

Do_Nothing 
Do_lnrc 
Do_Decr 
Do_Reset 

;; AT FFOh \ Do not generate an EXIT 



: Exec_Example ( n - - ) 

>R ' Jump_Table R> 

2* M+ \ calculate vector address 

EXECUTE 
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< CMP_LT 

4.8.51 Less-than Purpose: 'Less-than' comparison of the top two 4-bit values on the 

stack. If the second value on the stack is less than the top of 
stack value, then the BRANCH flag in the CCR is set. Unlike 
standard FORTH, whereby a BOOLEAN value (0 or 1), 
depending on the comparison result, is pushed onto the 
stack. 

Category: (<) : Comparison (single-length)/qFORTH macro 

(CMP_LT) : MARC4 mnemonic 

Library Implementation: 

CODE < CMP_LT ( n1 n2 -- n1 [BRANCH flag] ) 

DROP ( n1 -- ) 

END-CODE 
MARC4 Opcode: 08 hex (CMP_LT) 



Stack Effect: 


< 


EXP 


( n1 n2 -- ) 




CMP_LT 


EXP 


( n1 n2 -- n1 ) 




both 


RET 


(-- ) 


Stack Changes: 


EXP: 


< 


2 elements are popped from 








the stack 






CMP_LT 


top element is popped from 






the stack 






RET: 


not affected 




Flags: 


CARRY flag 


affected 






BRANCH flag 


Set, if (n1 < n2) 




X Y Registers: 


Not affected 






Bytes Used: 


1 -2 






See Also: 


<> = <=>=> <> Do D>= D<= 
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< CMP_LT 

Example: 

: LESS-THAN ( Check 5 < 7 and 8 < 6 and 5 < 5 ) 

5 7CMPJ.T (5 7-- 5 [ BRANCH and CARRY set ] ) 

86< ( 5 8 6 - 5 [ BRANCH is NOT set ] ) 

5 CMP_LT ( 5 5 -- 5 ) 
DROP 



MARC4 4-bit Microcontrollers Programmer's Guide 4-125 

4747A-4BMCU-01/04 



q FORTH Language Dictionary 



<= 



CMP LE 



4.8.52 Less-than-equal 



Purpose: 



Less-than-or-equal' comparison of the top two 4-bit values on 
the stack. If the 2nd value on the stack is less than, or equal 
to the top of stack value, then the BRANCH flag in the 
condition code register (CCR) is set. Unlike standard 
FORTH, whereby a BOOLEAN value (0 or 1), depending on 
the comparison result, is pushed onto the stack. 



Category: 



Library Implementation: 



MARC4 Opcode: 
Stack Effect: 



Stack Changes: 



(<=) 

(CMP_LE) 
CODE <= 
DROP 
END-CODE 
09 hex 
<= 

CMP_LE 

both 

EXP: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



: Comparison (single-length)/qFORTH 
macro 

: MARC4 mnemonic 

CMP_LE ( n1 n2 - n1 [BRANCH flag] ) 



(n1 - 

(CMP_LE) 
EXP 
EXP 
RET 

<= 

CMP_LE 



) 



( n1 n2 -- ) 
( n1 n2 -- n1 ) 
(-- ) 

2 elements are popped from the 
stack 

top element is popped from the 
stack 



RET: not affected 

CARRY flag affected 

BRANCH flag set, if (n1 <= n2) 

Not affected 

1 -2 

D<= 
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<= CMP_LE 

Example: 

: LESS-EQUALS ( show 7 <= 5 and 7 <= 7 and 8 <= 9 ) 

7 5CMPJ.E (75 --7 [ BRANCH flag NOT set ] ) 
7<= (77-- [BRANCH flag set] ) 

8 9 <= ( 8 9 - [ BRANCH and CARRY flag set ] ) 
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4.8.53 Not-equal 



<> 



CMP NE 



Purpose: 



Category: 

Library Implementation: 



MARC4 Opcode: 
Stack Effect: 



Stack Changes: 



Inequality test for the top two 4-bit values on the stack. If the 
2nd value on the stack is NOT equal to the top of stack value, 
then the BRANCH flag in the CCR is set. Unlike standard 
FORTH, whereby a BOOLEAN value (0 or 1), depending on 
the comparison result, is pushed onto the stack. 

(<>) : Comparison (single-length)/qFORTH macro 

(CMP_NE) : MARC4 mnemonic 

CODE <> CMP_NE ( n1 n2 -- n1 [BRANCH flag] ) 
DROP 



END-CODE 
07 hex (CMP_NE) 
<> EXP 
CMP_NE 
both 
EXP: 



EXP 
RET 



(n1 



( n1 n2 
( n1 n2 
(--) 



n1 



<> 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



RET: 

CARRY flag 



CMP_NE 

not affected 
affected 



2 elements are popped from the 
stack 

top element is popped from the 
stack 



BRANCH flag set, if (n1 <> n2) 
Not affected 
1 -2 

0<> 0= Do 
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<> CMP_NE 

Example: 

: NOT-EQUALS ( show 7 <> 5 and 7 <> 7 and 8 <> 9 ) 

7 5 CMP_NE ( 7 5 -- 7 [ BRANCH flag set ] ) 

7 <> ( 7 7 -- [ BRANCH flag NOT set ] ) 

8 9 <> ( 8 9 -- [ BRANCH and CARRY flag set ] ) 
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<ROT 



4.8.54 Left-rote 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



MOVE the TOS value to the third stack position, i.e. 
performs a LEFTWARD rotation 

Stack operation (single-length)/qFORTH macro 

CODE <ROT 

ROT ROT 

END-CODE 

EXP ( n1 n2 n3 - n3 n1 n2) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

2 

ROT 2<ROT 2 ROT 
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<ROT 

Example: 



: TD+ \ Add an 8-bit offset to a 1 2-bit value 

D+ \ Add the lower 8-bits ( t1 d2 -- n1 d3 ) 

IF \ IF an overflow to the 9th bit occurs, THEN 

ROT ( n1 d3 - d3 n1 ) 

1+ (d3n1~d3n1+1 ) 

<ROT (d3n1+1 --n1+1 d3 ) 

THEN ( n3 d3 -- 13 ) 
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4.8.55 Equal 



CMP EQ 



Purpose: 



Equality test for the top two 4-bit values on the stack. If the 
2nd value on the stack is equal to the top of stack value, then 
the BRANCH flag in the CCR is set. This is unlike standard 
FORTH, whereby a BOOLEAN value (0 or 1), depending on 
the comparison result, is pushed onto the stack. 



Category: 



Library Implementation: 



MARC4 Opcode: 
Stack Effect: 



(=) 



: Comparison (single-length)/qFORTH 
macro 



(CMP_EQ): 
CODE = 
DROP 
END-CODE 
06 hex (CMP_EQ) 
EXP 



MARC4 mnemonic 
CMP_EQ ( n1 n2 
(n1 - 



n1 [BRANCH flag] ) 



) 



Stack Changes: 



CMP_EQ 

both 

EXP: 



EXP 
RET 



( n1 n2 
( n1 n2 
(-- 



n1 



) 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



RET: 

CARRY flag 



CMP_EQ 

not affected 
affected 



2 elements are popped from the 
stack 

top element is popped from the 
stack 



BRANCH flag set, if (n1 = n2) 
Not affected 
1 -2 

0<> 0= Do D= 
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CMP_EQ 

Example: 

: EQUAL-TO ( show 7 = 5 and 7 = 7 and 8 = 9 ) 

7 5CMP_EQ ( 7 5 -- 7 [ BRANCH flag NOT set ] ) 
7= (77-- [ BRANCH flag set ] ) 

89= (89-- [ CARRY flag set ] ) 
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4.8.56 Greater-than 



CMP GT 



Purpose: 



'Greater-than' comparison of the top two 4-bit values on the 
stack. If the 2nd value on the stack is greater than the top of 
stack value, then the BRANCH flag in the CCR is set. This is 
unlike standard FORTH, whereby a BOOLEAN value (0 or 1 ), 
depending on the comparison result, is pushed onto the 
stack. 



Category: 



Library Implementation: 



MARC4 Opcode: 
Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



(>) 

(CMP_GT) 
CODE > 



: Comparison (single-length)/qFORTH 
macro 



: MARC4 mnemonic 
CMP_GT ( n1 n2 -■ 



DROP 



END-CODE 
OA hex (CMP_GT) 
EXP 



> 

CMP_GT 
both 
EXP: > 
CMP_GT 
RET: 

CARRY flag 



EXP 
RET 



(n1 



( n1 n2 
( n1 n2 



n1 [BRANCH flag] ) 
) 



n1 



( 



) 



2 elements are popped from the stack 
top element is popped from the stack 
not affected 
affected 



BRANCH flag set, if (n1 > n2) 
Not affected 
1 -2 

<<> = >= <> D> D>= Do D< 
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> CMP_GT 

Example: 

: GREATER-THAN ( check 5 > 7 and 8 > 6 and 5 > 5 ) 

5 7CMP_GT (57 --5 [ CARRY set ] ) 

86> ( 5 6 8 - 5 [ BRANCH set ] ) 

5 CMP_GT DROP (55-- ) 
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4.8.57 Greater-or-equal 



>= 



CMP GE 



Purpose: 



'Greater-than-or-equal' comparison of the top two 4-bit 
values on the stack. If the 2nd value on the stack is greater 
than or equal to the top of stack value, then the BRANCH flag 
in the condition code register (CCR) is set. Unlike standard 
FORTH, whereby a BOOLEAN value (0 or 1), depending on 
the comparison result, is pushed onto the stack. 



Category: 

Library Implementation: CODE >= 



(>=) : Comparison (single-length)/qFORTH macro 
(CMP_GE) : MARC4 mnemonic 



MARC4 Opcode: 
Stack Effect: 



Stack Changes: 



CMP_GE 
DROP 

END-CODE 

OB hex (CMP_GE) 



>= 

CMP_GE 

both 

EXP: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



RET: 

CARRY flag 



EXP 
EXP 
RET 



CMP_GE 

not affected 
affected 



(n1 n2 
(n1 - 



( n1 n2 
( n1 n2 

(" 



n1 [BRANCH flag]) 
) 



n1 



) 



2 elements are popped from 
the stack 

top element is popped from 
the stack 



BRANCH flag set, if (n1 >= n2) 
Not affected 
1 -2 

<> = <=<><> Do D>= D<= 
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>= CMP_GE 

Example: 

: GREATER-THAN-EQUALS ( show 7 >= 5 and 7 >= 7 and 8 >= 9 ) 

7 5CMP_GE (75-7 [ BRANCH flag set ] ) 
7>= (77-- [ BRANCH flag set ] ) 

8 9>= (89-- [ CARRY flag set ] ) 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-137 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



>R 



4.8.58 To-R 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Moves the top 4-bit value from the Expression Stack and 
pushes it onto the Return Stack. >R pops the EXP stack 
onto the RET stack. To avoid corrupting the RET stack 
and crashing the program, each use of >R must be 
followed by a subsequent R> within the same colon 
definition. 

Stack operation/assembler instruction 
22 hex 

EXP ( n1 -- ) 

RET (»u| u| n1) 

EXP: top element is popped from the stack 

RET: One element is pushed onto the stack 

Not affected 

Not affected 

1 

I - R> 2R@ 2>R 2R> 3R@ 3>R 3R> 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-138 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



Example: 



>R 



The sequence 



3 1 

>R 1- R> 



(-31 ) 
(31-21 ) 



temporarily moves the top value on the stack to the Return Stack so that the second 
value on the stack can be decremented. 



2<ROT 
ROT >R 
ROT >R 
ROT >R 
ROT R> 
R> R> 



\ Move top byte to 3rd position on stack 
( d1 d2 d3 - d1 d2h d3 
( d1 d2h d3 - d1 d3 
(d1 d3-d1hd3 
(d1hd3 - d3d1 
( d3 d1 - d3 d1 d2 



: JUGGLE-BYTES 
1 1 h 22h 33h 
2<ROT 
2SWAP 
20VER 



( - 1 1 h 22h 33h ) 
( 1 1 h 22h 33h - 33h 1 1 h 22h ) 
( 33h 1 1 h 22h - 33h 22h 1 1 h ) 
( 33h 22h 1 1 h - 33h 22h 1 1 h 22h 
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\7D0 



4.8.59 Query-DO 



Purpose: 



Category: 

Library Implementation: 



Indicates the start of a (conditional) iterative loop. 

?DO is used only within a colon definition in a pair with LOOP 
or +LOOP. The two numbers on top of the stack at the time 
?DO is executed determine the number of times the loop 
repeats. The value on top is the initial loop index and the next 
value is the loop limit. If the initial loop index is equal to the 
limit, the loop is not executed (unlike DO). The control is 
transferred to the statement directly following the LOOP or 
+LOOP statement and the two values are popped from the 
stack. 

Control structure/qFORTH macro 



Stack Effect: 



Stack Changes: 



CODE ?DO 



_$DO: 
END-CODE 
EXP 
RET 

RET 

EXP: 
RET: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



OVER CMP_EQ 2>R 
(S)BRA_$LOOP 



( limit index ~ 
( -- ullimitlindex 



(-- 



if LOOP is 
executed 

if LOOP is not 
executed 



2 elements are popped from the stack 

1 element is pushed onto the stack, if loop is 
executed and not affected, if loop is not 
executed 



CARRY flag affected 
BRANCH flag set, if (limit = index) 
Not affected 
5 

DO LOOP +LOOP 
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Example: 



?DOl 



VARIABLE Counter 
: QUERY-DO 

0 Counter ! 

6 0 DO 
I 0 

?DO Counter 1+! LOOP 
Counter @ 10 >= 7LEAVE 
LOOP 



( Counter := 0 

( repeat 6 times 

( copy limit, index start = 0 

( first time not executed 

( repeat,til count. >= 10 
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4.8.60 Query-doop 



?DUP 



Purpose: 



Category: 



Duplicates the top value on the stack only if it is not zero. 
?DUP is equivalent to the standard FORTH sequence 

DUP IF DUP THEN 

but executes faster. ?DUP can simplify a control structure 
when it is used just before a conditional test (IF, WHILE or 
UNTIL). 

Stack operation (single-length)/qFORTH macro 



Library Implementation: CODE ?DUP 



DUP OR 

(S)BRA_$ZERO 

DUP 



Stack Effect: 

Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



_$ZERO: 
END-CODE 
IFTOS = 0 

RET 



THEN EXP 
ELSE EXP 



(0- 
(n- 

(-- 



0 ) 
n n ) 

) 



EXP: A copy of the non zero top value is pushed onto the 
stack 

RET: not affected 

CARRY flag affected 

BRANCH flag set, if (TOS = 0) 

Not affected 

4-5 

DUP 0= 0<> 
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?DUP 

Example: 

: ShowByte ( b_high bjow -- b_high b_low ) 

DUP 3 OUT ( show a byte value as hexadecimal ) 

SWAP ( b_high bjow -- bjow b_high ) 

?DUP ( DUP and write only if non zero ) 

IF 2 OUT THEN ( suppress leading zero display ) 

SWAP ( restore nibble sequence ) 
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7LEAVE 



4.8.61 Query-leave 



Purpose: 



Conditional exit from within a control structure if the previous 
tested condition was TRUE (i.e., BRANCH flag is SET). 
7LEAVE is the opposite to -7LEAVE (condition FALSE). 

The standard FORTH word sequence IF LEAVE ELSE word 
.. THEN is equivalent to the qFORTH sequence 7LEAVE 
word ... 

7LEAVE transfers control just beyond the next LOOP, 
+LOOP or #LOOP or any other loop structure like BEGIN ... 
UNTIL, WHILE 



. REPEAT or BEGIN 
TRUE.E 



AGAIN if the tested condition is 



Category: 



Control structure/qFORTH macro 
Library Implementation: CODE 7LEAVE 

(S)BRA _$LOOP ( Exit LOOP if BRANCH set ) 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
Not affected 
Not affected 
1 -2 

-7LEAVE 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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7LEAVE 

Example: 



: QUERY-LEAVE 

3 BEGIN ( 3 = initial start value 

1 + ( increment count 3 -> 9 

DUP ( keep current value on the stack 

9 = 7LEAVE ( when stack value = 9 then exit loop 

AGAIN ( Indefinite repeat loop 

DROP ( the index 
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4.8.62 Fetch 



@ 



Purpose: 



Category: 



Copies the 4-bit value at a specified memory location to 
the top of the stack. 

Memory operation (single-length)/qFORTH macro 



Library Implementation: CODE 



Y! 

[Y]@ 



( addr 
(~n 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 

EXP ( RAM_addr - n ) 

RET ( - ) 

EXP: 1 element is popped from the stack 
RET: not affected 
Not affected 

The contents of the Y or X register may be changed 
2 

2@ 3@ ! 
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Example: 

VARIABLE DigitPosition 
8 ARRAY Result 
: DisplayResult 
7 DigitPosition ! 
BEGIN DigitPosition @ Fh <> 
WHILE DigitPosition @ DUP 
Result INDEX @ 
OVER 
OUT 

1- DigitPosition ! 
REPEAT 



( write ARRAY 'Result' [7]..[0] to ports 7..0 

( initialize position 

( REPEAT, until index = Fh 

( get digit pos: 7 .. 0 

( get digit [7] .. [0] 

( DPos val -- DPos val DPos 

( data port -- Display digit 

( decrement digit & store 

( REPEAT always;stop at WHILE 



: Display ( write 0 .. 7 to ARRAY 'Result' [0.] .. [7] ) 

8 0 DO 

I DUP Result INDEX ! 
LOOP 

DisplayResult ( 'call' display routine. ) 
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4.8.63 AGAIN 



AGAIN 



Purpose: 



Part of the (infinite loop) BEGIN ... AGAIN control structure. 
AGAIN causes an unconditional branch in program control to 
the word following the corresponding BEGIN statement. 



Category: Control structure/qFORTH macro 

Library Implementation: CODE AGAIN 

SET_BCF ( execute an unconditional branch ) 
(S)BRA _$BEGIN 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag set 
BRANCH flag set 
Not affected 
2-3 

BEGIN UNTIL WHILE REPEAT 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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Example: 



AGAIN 



INFINITE-LOOP 
3 BEGIN 

1 + 

DUP 

9 = 7LEAVE 
AGAIN 



( 3 = initial start value 

( increment count 3 -> 9 

( keep current value on the stack 

( when stack value = 9 then exit loop 

( repeat unconditional 
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ALLOT 



4.8.64 ALLOT 



Purpose: 

Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Allocate (uninitialized) RAM space for the two stacks and 
global data of the type VARIABLE or 2VARIABLE. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

VARIABLE 2VARIABLE 
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Example: 



ALLOT 



VARIABLE Limits 7 ALLOT 

VARIABLE RO 31 ALLOT 
VARIABLE SO 19 ALLOT 



( Allocates 8 nibbles for the 
( variable LIMITS 

( allocate space for RETURN stack 
( allot 20 nibbles for EXP stack 
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AND 



4.8.65 AND 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Bit-wise AND of the top two 4-bit stack elements leaving the 
4-bit result on top of the Expression Stack. 

Arithmetic/logical (single-length)/assembler instruction 

05 hex 

EXP ( n1 n2 -- n1 A n2 ) 

RET ( - ) 

EXP: top element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag set if (TOS = 0) 

Not affected 

1 

NOT OR XOR 
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AND 



Example: 



: ERROR 



( what shall happen in error case: ) 



3R@ 



3#D0 



( show PC, where CPU fails 
( suppress compiler warnings. 



I OUT [EO] 



#LOOP 



: Logical 



1001b 1100b 
AND 

1000b <> IF ERROR THEN 
1010b 0011b 
AND 

0010b <> IF ERROR THEN 
1001b 1100b 
OR 

1 101b <> IF ERROR THEN 
1010b 0011b 
OR 

1011b <> IF ERROR THEN 
1001b 1100b 
XOR 

0101b <> IF ERROR THEN 
1010b 0011b 
XOR 

1001b <> IF ERROR THEN 
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ARRAY 



4.8.66 ARRAY 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes used: 
See Also: 



Allocates RAM space for storage of a short single-length 
(4-bit/nibble) array, using a 4-bit array index value. 
Therefore the number of 4-bit array elements is limited to 
16. 

The qFORTH syntax is as follows: 

<number> ARRAY <name> [ AT <RAM-Addr> ] 

At the time of compilation, ARRAY adds <name> to the 
dictionary and ALLOTs memory for storage of <number> 
single-length values. At execution time, <name> leaves 
the RAM start address of the parameter field (<name> 
[0]) on the expression stack. 

The storage ALLOTed by an ARRAY is not initialized. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

2ARRAY LARRAY Index ERASE 
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ARRAY 



Example: 

6 ARRAY RawDATA AT 1 Eh ( RawDATA[0] . . . RawD ATA[5] ) 



: lnit_ARRAY 

5 ( set initial value := 5 ) 

6 0 DO ( array index from 0 ... 5 ) 

DUP I RawDATA INDEX ! ( indexed store ) 
1 - ( decrement store value ) 

LOOP 
DROP 

( The result is: RawDATA[0] := 5 stored in RAM location 1 E ) 

( RawDATA[1] := 4 stored in RAM location 1 F ) 

( RawDATA[2] := 3 stored in RAM location 20 ) 

( RawDATA[3] := 2 stored in RAM location 21 ) 

( RawDATA[4] := 1 stored in RAM location 22 ) 

( RawDATA[5] := 0 stored in RAM location 23 ) 
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AT 



4.8.67 AT 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Specifies the ABSOLUTE memory location AT where either a 
variable is placed in RAM, a L/U table, string or a qFORTH 
word (subroutine/interrupt service routine) is forced to be 
placed in the ROM area. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

VARIABLE ARRAY ROMCONST 
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AT 



Example: 



VARIABLE State AT 3 



: CheckState 



State @ 



( fetch current state from RAM loc. 3 



CASE 

0 OF State 1 +! ( increment contents of variable state ) 
ENDOF 
15 OF State 1-! 
ENDOF 
ENDCASE 

[ Z ] ; Test_Status ( force placement in ZERO page ) 

: INTO_Service 
Fh State ! 
BEGIN 

CheckState 

State 1-! 

UNTIL 

; AT 400h ( force placement at ROM address 400h ) 
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BEGIN 



4.8.68 BEGIN 



Purpose: 



Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Indicates the start of one of the following control 
structures: 

BEGIN ... UNTIL 

BEGIN ... AGAIN 

BEGIN ... WHILE .. REPEAT 

BEGIN marks the start of a sequence that may be 
repetitively executed. It serves as a branch destination 
(_$BEGINxx:) for the corresponding UNTIL, AGAIN or 
REPEAT statement. 

Control structure 

CODE BEGIN 

_$BEGIN: [EORO] 

END-CODE 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

UNTIL AGAIN REPEAT WHILE ? LEAVE -7LEAVE 
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BEGIN 



Example: 



: BEGIN-UNTIL 



3 BEGIN 



( increment value from 3 til 9 

( DUP the current value because the 

( comparison will DROP it 



1+DUP9 = 



UNTIL 



DROP 



( BRANCH and CARRY flags will be set 



: BEGIN-AGAIN 



( do the same with an infinite loop 



3 BEGIN 

1+ DUP 
9 = 7LEAVE 
AGAIN 

DROP 



: BEGIN-WHILE-REPEAT ( do the same with a WHILE-REPEAT loop) 
3 BEGIN 

DUP9<> 

WHILE ( REPEAT increment while not equal 9 ) 

1 + 
REPEAT 
DROP 
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CASE 



4.8.69 CASE 



Purpose: 



Indicates the start of a CASE ... OF ... ENDOF ... ENDCASE 
control structure. Using a 4-bit index value on TOS, CASE 
compares it sequentially with each value in front of an OF ... 
ENDOF pair until a match is found. When the index value 
equals one of the 4-bit OF values, the sequence between 
that OF and the corresponding ENDOF is executed. Control 
then branches to the word following ENDCASE. 

If no match is found, the ENDCASE will DROP the index 
value from the EXP stack. The 'otherwise' case may be 
handled by qFORTH words placed between the last ENDOF 
and ENDCASE. 

Note: However, the 4-bit index value must be perserved across 
the 'otherwise' sequence so that ENDCASE can drop it 



Category: Control structure 

Library Implementation: CODE CASE 

_$CASE: [EO RO] 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 
EXP ( n -- n ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
Not affected 
Not affected 
0 

OF ENDOF ENDCASE 
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Example: 



CASE 



5h CONSTANT Keyboard 

1 CONSTANT TestPortl 

: ONE 1 TestPortl OUT ; 

: TWO 2 TestPortl OUT ; 

: THREE 3 TestPortl OUT ; 

: ERROR DUP TestPortl OUT ; 

( duplicate value for the following ENDCASE; 

: CASE-Example 

Key Board IN 

CASE 

1 OF ONE ENDOF 

2 OF TWO ENDOF 

3 OF THREE ENDOF 
ERROR 

ENDCASE 



( write 1 to the TestPortl ' 
(write 2 to the TestPortl' 
( write 3 to the TestPortl ' 
( dump wrong input to the port 
it drops one 

( request 1 -digit keyboard input 
( depending of the input value, 
( one of these words will be 
( activated. 

( otherwise ... 
(n- 
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CCR! 



4.8.70 CCR-store 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



Store the 4-bit TOS value in the condition code register 
(CCR). 

Note: All flags will be altered by this command 
Assembler instruction 
0E hex 
EXP ( n -- ) 
RET ( - ) 

EXP: 1 element is popped from the stack 
RET: not affected 

CARRY flag set, if bit 3 of TOS was set 
BRANCH flag set, if bit 1 of TOS was set 
LENABLE flag set, if bit 0 of TOS was set 
Not affected 
1 

El Dl CCR@ SET_BCF CLR_BCF 
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Example 1 : 



CCR! 



: INT5 



CCR@ 

lnc_Time 

CCR! 



( timer interrupt service routine 
( save the current condition codes 
( call procedure. 
( restore CCR status 
( RTI 



Note: CCR®/! and X/Y @/! will be inserted in INTx-routines by the compiler automatically. 



Example 2: 

CODE El ( enable all interrupts ) 

0001b CCR! 
END_CODE 
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CCR@ 



4.8.71 CCR-fetch 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Save the contents of the condition code register on TOS. 
Assembler instruction 
OD hex 
EXP ( -- n) 
RET(- ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

1 

CCR! El Dl 
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CCR@ 



Example: 

1 CONSTANT Portl 



: 7ERROR ( error routine: are the numbers equal ? ) 

<> IF ( if unequal, then write Fh to Portl . ) 
Fh Portl OUT 

THEN ( two digits are dropped from the stack ) 

> 

: ADD_ADDC_TEST ( add up to 8-bit numbers ) 

AhCh+ ( 10 12 -- 6 + CARRY flag set ) 

CCR@ SWAP ( 6 -- [C-BI flags] 6 ) 

6 7ERROR ( check correct result (66--) ) 

CCR! ( restore CARRY flag setting ) 

Dh 6h +C (13 6 [CARRY] - 4 + CARRY flag set ) 

4 7ERROR ( check correct result ( 4 4 - ) ) 
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CLR BCF 



4.8.72 Clear BRANCH- and 
CARRY-Flag 



Purpose: 



Clear the BRANCH and CARRY flag in the condition code 
register. 



Category: q FORTH macro 

Library Implementation: CODE CLR_BCF 

0 ADD 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



( reset CARRY & BRANCH flag ) 



END-CODE 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag reset 

BRANCH flag reset 

Not affected 

2 

SET_BCF TOG_BF 
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Example: 



CLR BCF 



8 ARRAY Result 
: DIG+ 

Y! CLR_BCF 

8#D0 

[Y]@ +C DAA 
[Y-]! 0 
-? LEAVE 
#LOOP 
DROP 



ADD-UP-NUMBERS 
Result 8 ERASE 
15 #DO 

9 Result [7] 
DIG+ 
#LOOP 



8-digit BCD number array definition 

add 1 digit to an 8-digit BCD number 

digit LSD_addr -- digit ; clear figs 

loop maximal 8 times. 

add digit & do a decimal adjust. 

store; add 0 to the next digit. 

if no more carry, then leave loop. 

last 0 is not used. 
EXIT - return 



clear the array, 
loop 15 times. 

put address of last nibble to TOS.-1 
add 15 times 9 to RESULT 
BRANCH conditionally to begin of loop 
result: 9* 15 = 135 
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CODE 



4.8.73 CODE 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Begins a qFORTH macro definition where both MARC4 
assembler instructions and qFORTH words may be included. 
Macros defined as CODE ... END-CODE are executed 
identically to words created as colon definitions ( i.e. :...;)- 
except that no CALL and EXIT is placed in the ROM. The 
macro bytes are placed from the compiler in the ROM to 
every program sequence where they should be activated. 
MACROs are often used to improve run-time optimization, as 
long as the macro is not used too often by the program. 

Note: qFORTH word definitions that change the Return Stack 
level (>R, 2>R, ... 3R>, DROPR) require CODE ... 
END-CODE implementations, because the return address 
would no longer be available. 

Predefined structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

END-CODE colon definition (:) EXIT (;) 
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CODE 

Example: 

5 CONSTANT Port5 

3 ARRAY ReceiveData ( 12-bit data item ) 

( CODE to shift right a 1 2-bit data word ) 

CODE ShiftRDBits 

ReceiveData Y! 

[Y]@ ROR [Y]! 

[+Y]@ ROR [Y]! ( rotate thru CARRY ) 

[+Y]@ ROR [Y]! 
END-CODE 



: Receive_Bit 

ReceiveDate Y! ( write data to the array: ) 

5 [Y]! Ah [+Y]! 1 [+Y]! 

Port5 IN SHL ( Read input from IP53 ) 

ShiftRDBits ( shift 'ReceiveData' 1 bit right ) 
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q FORTH Language Dictionary 



4.8.74 Dollar-Include 



$INCLUDE 



Purpose: 



Category: 
Stack Changes: 

Flags: 



Compiles qFORTH source code from another text file. Used 
in form 

$INCLUDE <filename> 

$INCLUDE loads a qFORTH program from an ASCII text file. 
Such a source text file may be created using any standard 
text editor. 

$INCLUDE is "state-smart" and may be used (together with a 
filename) inside of a colon definition. 

The file name extension 'INC is the default and may be 
omitted. 

Compiler 

EXP ( - - ) 

RET ( - - ) 

Not affected 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-170 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



$INCLUDE 

Example: 

The sequence $INCLUDE MYPROG.SCR causes the qFORTH source code in file 
MYPROG.SCR to be compiled. 
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q FORTH Language Dictionary 



4.8.75 Dollar-RAMSize 
Dollar-ROMSize 



$RAMSIZE $ROMSIZE 



Purpose: 



Category: 
SRAMSIZE: 



SROMSIZE: 



The MARC4 qFORTH compiler's behavior during compilation 
may be controlled by including $-Sign directives within the 
source-code file. These $-sign directives consist of one keyword 
which may be followed by at least one parameter. For more 
details refer to the "MARC4 User's Guide" 

Compiler directives 

Specifies the RAM size of the target processor. Default size is 
255 nibbles (from $00 .. $FF). Some processors contain 253 
nibbles only, whereby the RAM cells at $FC, $FD and $FE are 
not available. 

Specifies the ROM size of the target processor. Default size is 
4.0K (from $000 .. $FFF) ; The constants are as follows: 
1 .OK = 3Fh, 2.5K = 9Fh and 4.0K = FFh. With '$ROMSIZE' you 
can access this 8-bit constant in your source program. 
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$RAMSIZE $ROMSIZE 

Example: 

$INCLUDE Timer.INC 
( Predefined constants: 
255 2C0NSTANT $RAMSIZE 
1 .5k 2C0NSTANT $ROMSIZE 

VARIABLE RO 27 ALLOT 
VARIABLE SO 19 ALLOT 



( for 253 RAM nibbles [3 auto sleep] 
( 1535 ROM bytes - 2 b. for check sum 
( resulting constant [$ROMSIZE] = 5Fh 
( return stack: 28 nibbles for 7 level 
( data stack: 20 nibbles 
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q FORTH Language Dictionary 



CONSTANT 



4.8.76 CONSTANT 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Creates a 4-bit constant; implemented in a qFORTH 
program as: 

n CONSTANT <name> 

with 0 <= n <= 15 or 0 <= n <= Fh or 0000b <= 
n <= 1111b 

Creates a dictionary entry for <name>, so that when 
<name> is later 'executed', the value n is left on the 
stack.This is similar to an assembler equate statement in 
that it assigns a value to a symbol. 

Predefined data structure 

EXP ( -- n ) on runtime. 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

2CONSTANT VARIABLE 2VARIABLE 
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CONSTANT 



Example: 

4h CONSTANT #Nibbles 
20 2CONSTANT Nr_of_Apples 
03h 2CONSTANT Nr_of_Bananas 
8 CONSTANT NumberOfBits 
001 1 b CONSTANT BitMask 



( value of valid bits ) 

( value > 15 [Fh] ) 

( hexadecimal, decimal or ) 

( binary. ) 



Example: 

Nr_of_Apples Nr_of_Bananas 
D+ 

DUP BitMask AND DROP 
IF 

NumberOfBits 
#DO ... #LOOP 
THEN 



( calculate nr of fruits ) 
( lower nibble: odd or even ? ) 

( do it with every bit: ) 
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q FORTH Language Dictionary 



D+ 



4.8.77 D-plus 



Purpose: 



Category: 



Library Implementation: 



D+ adds the top two 8-bit values on the stack and leaves 
the result on the Expression Stack. 

Arithmetic/logical (double-length)/qFORTH colon 
definition 



D+ ROT ( d1 h d1 1 d2h d2l -- d1 h d2h d2l d1 1 

ADD ( d1 h d2h d2l d1 1 -- d1 h d2h d3l 

<ROT ( d1 h d2h d3l -- d3l d1 h d2h 

ADDC (d3ld1hd2h--d3ld3h 

SWAP ( d3l d3h -- d3 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 -- d_sum ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 
RET: not affected 

CARRY flag set on overflow on higher nibble 
BRANCH flag = CARRY flag 
Not affected 
7 

D- 2! 2@ D+! D-! D2/ D2* 
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q FORTH Language Dictionary 



Example: 



D+ 



DC Double Add 
10h 0 5 D+ 
18h D+ 
14h D+ 

COh D+ 2DROP 



( result: -- 15 ; no flags ) 

( result: -- 2D ; no flags ) 

( result: -- 41 ; no flags ) 

( result: --01 ; C & B flag ) 
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q FORTH Language Dictionary 



D+! 



4.8.78 D-plus-store 



Purpose: 
Category: 

Library Implementation: 



ADD the TOS 8-bit value to an 8-bit variable in RAM and 
store the result in that variable. On function entry, the 
higher nibble address of the variable is the TOS value. 

Arithmetic/logical (double-length)/qFORTH colon 
definition 

: D+! 



Y! 


( nh nl address - nh nl 


[+Y]@ + 


( nh nl - nh nl' 


[Y-]! 


( nh nl' - nh 


[Y]@ +c 


( nh -- nh' 


[Y]! 


( nh' -- 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (d RAM_addr - ) 
RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 

CARRY flag set on overflow on higher nibble 

BRANCH flag = CARRY flag 

The contents of the Y register will be changed 

8 

The other double-length qFORTH dictionary words, like 
D- D+ 2! 2@ D-! D2/ D2* D< D> Do D= D<= 
D>= D0= DOo 
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q FORTH Language Dictionary 



D+! 

Example: 

2VARIABLE count AT 43h 

: Double_Arithm 
13hcount2! ( RAM [43] = 1 ; RAM [44] = 3 ) 

count 2@ (--13 ) 

2DR0P 

55h count D+! ( 68 in the RAM ; no flags ) 

b5h count D+! ( 1 D in the RAM ; C & B flag ) 
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q FORTH Language Dictionary 



D- 



4.8.79 D-minus 



Purpose: 
Category: 

Library Implementation: 



D- subtracts the top two 8-bit values on the EXP stack and 
leaves the result on the EXP stack. 

Arithmetic/logical (double-length)/qFORTH colon definition 

: D- ROT ( d1 h d1 1 d2h d2l -- d1 h d2h d2l d1 1 

SWAP ( d1 h d2h d2l d1 1 — d1 h d2h d1 1 d2l 

SUB (d1hd2hd1ld2l--d1hd2hd3l 

<ROT (d1hd2hd3l--d3ld1hd2h 

SUBB (d3ld1hd2h--d3ld3h 

SWAP ( d3l d3h -- d3 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP(d1 d2-d1-d2 ) 

RET ( - ) 

EXP: 2 elements are popped from the stack 

RET: not affected 

CARRY flag set on arithmetic underflow 
BRANCH flag = CARRY flag 
Not affected 
8 

D+ 2! 2@ D+! D-! D2/ D2* D< D> 
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D- 

Example: 

: Double_Minus 
15h 13h 

D- 2DR0P ( result: -- 02 ; no flags ) 

13h 15h 

D- 2DROP ( result: -- FE ; C & B flag ) 

18h 18h D- ( result: -- 00 ; no flags ) 

D0= ( result: -- ; B flag set ) 
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D-! 



4.8.80 D-minus-store 



Purpose: 
Category: 

Library Implementation: 



Subtract the top 8-bit value from an 8-bit variable in RAM and 
store the result in that variable. The address of the variable is 
the TOS value. 

Arithmetic/logical (double-length)/qFORTH colon definition 
D-! 



Y! 


( nh nl address -- nh nl 


[+Y]@ 


( nh nl -- nh nl @RAM[Y] 


SWAP - 


( nh nl @RAM[Y] -- nh nl 


[Y-]! 


( nh nl' - nh 


[Y]@ 


( nh -- nh @RAM[Y+1] 


SWAP -c 


( nh @RAM[Y+1] -- nh' 


[Y]\ 


( nh 1 -- 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (d RAM_addr 
RET ( -- 



) 



EXP: 4 elements are popped from the stack 
RET: not affected 

CARRY flag set on arithmetic underflow 

BRANCH flag = CARRY flag 

The contents of the Y register are changed 

10 

D- D+ 2! 2@ D+! 
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D-! 

Example: 

2VARIABLE Fred 
: DCompAri 
13h Fred 2! 

1 1 h Fred D-! ( 02 in the RAM ; no flags ) 

1 1 h Fred D-! ( F1 in the RAM ; C & B flag set ) 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-183 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.8.81 D-zero-not-equal 



DOo 



Purpose: 



Category: 



Compares the 8-bit value on top of the stack with zero. 
Instead of pushing a Boolean TRUE flag on the stack if the 
byte on top of the stack is non-zero, 'DOo' sets the BRANCH 
flag in the CCR. 

Arithmetic/logical (double-length)/qFORTH macro 



Library Implementation: CODE DOo OR 



( n1 n2 - n3 [if 0 then BRANCH 
flag] ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 

EXP 

RET 



DROP 
TOG_BF 

(d- 
(" 



(n3 -- 

( Toggle BRANCH flag 



) 



) 



) 



EXP: 2 elements will be popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag Set, if (d <> 0) 

Not affected 

3 

D- D+ D< D> Do D= D<= D>= D0= 
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DOo 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 

12h DOo 

IF true ELSE false THEN DROP( result is 'true' ) 
12h D- DOo 

IF true ELSE false THEN DROP( result is 'false' ) 




4-185 



4747A-4BMCU-01/04 
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4.8.82 D-zero-equal 



D0= 



Purpose: 



Category: 



Compare the 8-bit value on top of the stack to zero. Instead 
of pushing a Boolean TRUE flag on the stack if the byte on 
top of the stack is zero, 'D0=' sets the BRANCH flag in the 
CCR. 

Arithmetic/logical (double-length)/qFORTH macro 



Library Implementation: CODE D0= OR 

DROP 



( n1 n2 -- n3 [BRANCH flag re/set]) 
( n3 -- [BRANCH flag] ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See also: 



END-CODE 
EXP ( d - ) 
RET(- ) 

EXP: 2 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag set, if (d = 0) 

Not affected 

2 

D- D+ D< D> Do D= D<= D>= DOo 
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D0= 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h D0= 

IF true ELSE false THEN DROP ( result is 'false' ) 

12h DO- D0= 

IF true ELSE false THEN DROP ( result is 'true' ) 
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02" 



4.8.83 D-two-multiply 



Purpose: 
Category: 



Multiplies the 8-bit value on top of the stack by 2. 
Arithmetic/logical (double-length)/qFORTH macro 



Library Implementation: CODE D2 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



( dh dl -- dh dl*2 
( dh dl*2 -- dl*2 dh 
( dl*2 dh -- dl*2 dh*2 
( dl*2 dh*2 -- d*2 



(d- 
(-- 



d*2 ) 
) 



SHL 
SWAP 
ROL 
SWAP 

END-CODE 
EXP 
RET 
EXP: not affected 
RET: not affected 

CARRY flag set on arithmetic overflow 
BRANCH flag = CARRY flag 
Not affected 
4 

D- D+ D2/ Do D= D<= D>= D0= DOo 
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q FORTH Language Dictionary 



D2* 

Example: 

: DMultiply 
03 

D2* ( 03h -> 06h and no flags ) 

D2* ( 06h -> OCh and no flags ) 

D2* 2DROP ( OCh -> 1 8h and no flags ) 

90h D2* 2DROP ( 90h -> 20h and C & B flag ) 

; ( [90h *2 = 120h] ) 
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\D2f 



4.8.84 D-two-divide 



Purpose: 
Category: 



Divides the 8-bit value on top of the stack by 2. 
Arithmetic/logical (double-length)/qFORTH macro 



Library Implementation: CODE D2/ 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



SWAP ( dh dl/2 -- dl dh ) 
SHR ( dl dh -- dl dh/2 [CARRY flag] ) 

SWAP ( dl dh/2 [CARRY flag] -- dh/2 dl) 
ROR ( dh/2 dl [CARRY flag] -- d/2 ) 

END-CODE 

EXP ( d - d/2) 

RET ( - ) 

EXP: not affected 
RET: not affected 

CARRY flag set, if LSB of byte on TOS has been set 
BRANCH flag = CARRY flag 
Not affected 
4 

D- D+ D+! D-! D2* Do D= 
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D2/ 

Example: 



: D2Divide 
13h 

D2/ ( 1 3h -> 09h and C & B flag ) 

D2/ ( 09h -> 04h and C & B flag ) 

D2/ ( 04h -> 02h and no flags ) 

D2/ ( 02h -> 01 h and no flags ) 

D2/ 2DROP ( 01 h -> OOh and C & B flag ) 
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D< 



4.8.85 D-less-than 



Purpose: 



Category: 

Library Implementation: 



'Less-than' comparison for the top two unsigned 8-bit values. 
Instead of pushing a boolean TRUE flag onto the stack if the 
2nd value on the stack is 'less-than' the TOS value, 'D<' sets 
the BRANCH flag. 

Arithmetic/logical (double-length)/qFORTH colon definition 



: D< ROT 

2>R 

OVER 

CMP_LT 

BRA _BIGGER 

CMP_LT 

BRA _IS_LESS 

2R@ 

CMP_LE 
_BIGGER: TOG_BF 

DROP 
_IS_LESS: DROP 

DROPR 

[ E -4 R 0 ] 



( d1 d2 -- d1h d2 d1l 
(d1hd2h d2ld1l--d1hd2h 
( d1h d2h -- d1h d2h d1h 
(d1hd2hd1h--d1hd2h [B-flag 
( jump if upper nibble is bigger 
( d1 h d2h - d1 h [BRANCH flag 
( jump if upper nibble is smaller' 
(dlh~dlhd2ldll 
(dlhd2ldll~dlhd2l 
( correct the BRANCH flag 
(d1hd2l -d1h 
(d1h - 

( skip lower nibbles from RET 



stack 



) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP 
RET 



( d1 d2 - ) 



( 



) 



EXP: 4 elements are popped from the stack 

RET: not affected 

CARRY flag affected 

BRANCH flag = set, if (d1 < d2) 

Not affected 

16 

D> Do D= D<= D>= D0= D0<> 
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q FORTH Language Dictionary 



D< 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h D< 

IF true ELSE false THEN DROP ( result is 'true' ) 

15h 12h D< 

IF true ELSE false THEN DROP ( result is 'false' ) 

18h 18h D< 

IF true ELSE false THEN DROP ( result is 'false' ) 
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D<= 



4.8.86 D-less-equal 



Purpose: 'Less-than-or-equal' comparison for the top two unsigned 

8-bit values. Instead of pushing a Boolean TRUE flag on the 
stack if the 2nd number on the stack is 'less-or-equal-than' 
the TOS number, 'D<=' sets the BRANCH flag. 

Category: Arithmetic/logical(double-length)/qFORTH colon definition 

Library Implementation: CODE D<= D> 

TOG_BF 

END-CODE 

EXP ( d1 d2 -- ) 

RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 
CARRY flag affected 
BRANCH flag = set, if (d1 <= d2) 
Not affected 
'D>' ± 1 

D< D> Do D= D>= D0= D0<> 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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q FORTH Language Dictionary 



D<= 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h D<= 

IF true ELSE false THEN DROP ( result is 'true' ) 

15h 12h D<= 

IF true ELSE false THEN DROP ( result is 'false' ) 

18h 18h D<= 

IF true ELSE false THEN DROP ( result is 'true' ) 
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Do 



4.8.87 D-not-equal 



Purpose: Inequality test for the top two 8-bit values. Instead of pushing 

a Boolean true flag onto the stack if the 2nd value on the 
stack is 'not-equal' to the TOS value, 'Do' sets the BRANCH 
flag. 

Category: Arithmetic/logical(double-length)/qFORTH colon definition 

Library Implementation: Do ROT ( d1h d1l d2h d2l -- d1h d2h d2l d1l ) 

CMP_NE (d1hd2hd2ld1l -d1hd2hd2l ) 



DROP 



( d1h d2h d2l -- d1h d2h 



BRA _NOT_EQ 



CMP NE 



DUP 

_NOT_EQ: 2DROP 
[E-4 RO] 



( jump if lower nibbles not 
equal 

(d1hd2h -d1h 
[BRANCH flag] 

(d1h»d1hd1h 

(d1hd2h -- 



) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 -- ) 
RET ( - ) 

EXP: 4 elements are popped from the stack 

RET: not affected 

CARRY flag affected 

BRANCH flag = set, if (d1 <> d2) 

Not affected 

10 

D< D> D= D<= D>= D0= DOo 
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Do 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h Do 

IF true ELSE false THEN DROP ( result is 'true' ) 

15h 12h Do 

IF true ELSE false THEN DROP ( result is 'true' ) 

18h 18h Do 

IF true ELSE false THEN DROP ( result is 'false' ) 
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D= 



4.8.88 D-equal 



Purpose: Equality test for the top two 8-bit values. Instead of pushing a 

boolean TRUE flag onto the stack if the 2nd value is 'equal' to 
the TOS value, 'D=' sets the BRANCH flag. This macro uses 
the colon definition 'Do'. 

Category: Arithmetic/logical(double-length)/qFORTH macro 

Library Implementation: CODE D= 

Do 

TOG_BF 

END-CODE 

EXP ( d1 d2 -- ) 

RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 
CARRY flag affected 
BRANCH flag = set, if (d1 = d2) 
Not affected 
'Do' ± 1 

D< D> Do D<= D>= D0= DOo 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Register: 
Bytes Used: 
See Also: 
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D= 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h D= 

F true ELSE false THEN DROP ( result is 'false' ) 

15h 12h D= 

IF true ELSE false THEN DROP ( result is 'false' ) 

18h 18h D= 

IF true ELSE false THEN DROP ( result is 'true' ) 
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D> 



4.8.89 D-greater-than 



Purpose: 



Category: 

Library Implementation: 



'Greater-than' comparison for the top two 8-bit values. 
Instead of pushing a Boolean TRUE flag onto the stack if the 
2nd value is 'greater-than' to the TOS value, 'D>' sets the 
BRANCH flag. 

Arithmetic/logical(double-length)/qFORTH colon definition 



: D> ROT 
2>R 
OVER 
CMP_GT 

BRA .SMALLER 

CMP_GT 

BRA JSJHUGH 

2R@ 

CMP_GE 
.SMALLER: TOG_BF 

DROP 
JSJHUGH: DROP 

DROPR 

[E-4 RO] 



d1 d2 -- d1h d2 d1l 

d1h d2h d2l d1 1 — d1h d2h 

d1h d2h -- d1h d2h d1h 

d1h d2h d1h -- d1h d2h 
B-flag] 

jump if upper nibble is smaller' 

d1hd2h -d1h [BRANCH flag 

jump if upper nibble is bigger 

d1h - d1h d2l d1l 

dlhd2ldll"dlhd2l 

correct the BRANCH flag 

d1h d2? -- d1h 

d1h -- 

skip lower nibbles from 
RET stack ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 d2 -- ) 

RET ( - ) 

EXP: 4 elements are popped from the stack 

RET: not affected 

CARRY flag affected 

BRANCH flag = set, if (d1 > d2) 

Not affected 

16 

D< Do D= D<= D>= D0= D0<> 
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D> 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h D> 

IF true ELSE false THEN DROP ( result is 'false' ) 

15h 12h D> 

IF true ELSE false THEN DROP ( result is 'true' ) 

18h 18h D> 

IF true ELSE false THEN DROP ( result is 'false' ) 
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q FORTH Language Dictionary 



D>= 



4.8.90 D-greater-equal 



Purpose: 'Greater-than-or-equal' comparison for the top two 8-bit 

values. Instead of pushing a Boolean TRUE flag onto the 
stack if the 2nd value is 'greater-than-or-equal' to the TOS 
value, 'D>=' sets the BRANCH flag. 

Category: Arithmetic/logical(double-length)/qFORTH colon definition 

Library Implementation: CODE D>= D< 

TOG_BF 

END-CODE 

EXP ( d1 d2 -- ) 

RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 
CARRY flag affected 
BRANCH flag = set, if (d1 >= d2) 
Not affected 
'D<' ± 1 

D< D> Do D= D<= D0= D0<> 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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q FORTH Language Dictionary 



D>= 



Example: 

1 CONSTANT true 
0 CONSTANT false 
: DCompare 
12h 15h D>= 

IF true ELSE false THEN DROP ( result is 'false' ) 

15h 12h D>= 

IF true ELSE false THEN DROP ( result is 'true' ) 

18h 18h D>= 

IF true ELSE false THEN DROP ( result is 'true' ) 
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\D>S 



NIP 



4.8.91 Double-to-single 
NIP 



Purpose: 



Transform an 8-bit value into a 4-bit value. Drops second 
4-bit value from the stack. 



Category: Stack operation (single-length)/qFORTH macro 

Library Implementation: CODE D>S I NIP 

SWAP ( d -- n 0 ) or ( n1 n2 ~ n2 n1 ) 
DROP ( n 0 -- n ) ( n2 n1 - n2 ) 

END-CODE 

EXP ( d -- n ) or EXP ( n1 n2 ~ n2 ) 
RET ( - ) 

EXP: 1 element is popped from the stack 
RET: not affected 
Flags: Not affected 

X Y Registers: Not affected 

Bytes Used: 2 
See Also: S>D 2NIP 



Stack Effect: 



Stack Changes: 
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D>S NIP 

Example 1 : 

: NIP_Example 
10H 
3 

NIP 

2DR0P 



(-10 ) 

(10-103 ) 

(10 3-13 ) 

(13 - ) 



Example 2: 

: StoD_DtoS 

4 ( -4 ) 

S>D (4-04 ) 

D>S (04-4 ) 

DROP (4- ) 



Example 3: 

Library implementation: of 'DEPTH' 

: DEPTH SP@S0D- ( - SPh SPI SOh SOI - diff ) 

NIP 1- ( diff — n ) 
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DAA 



4.8.92 Decimal Adjust 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Decimal-arithmetic-adjustment for BCD arithmetic if the digit on 
top of stack is greater than 9, or the CARRY flag is set. 

Assembler instruction 

16 hex 

IFTOS>9or CARRY-in = 1 

THEN EXP ( n -- n+6 ) 

ELSE EXP ( n -- n ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag set, if (TOS > 9) or (CARRY-in = 1) 
BRANCH flag = CARRY flag 
Not affected 
1 

+C DAS SET_BCF 
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Example 



DAA 



: DAA_Example 
2 SET_BCF DAA 
2 CLR_BCF DAA 
11 DAA 

Bh SET_BCF DAA 
2DR0P 2DR0P 



( result is: 2 -- 8 & C flag ) 
( result is: 2 -- 2 no flag ) 
( result is: B -- 1 & C flag [Bh = 11]) 
( result is: B -- 1 & C flag ) 



Another example for DAA, see DAS entry (next page). 
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Idas 



4.8.93 D-A-S or 

Decimal-Adjust for 
Subtraction 



Purpose: 



Decimal arithmetic for BCD subtraction, computes a 9's 
complement. 



Category: q FORTH macro 

Library Implementation: CODE DAS 

NOT 10+c 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



9-n ) 
) 



( n -- 9-n ) 

END-CODE 
EXP ( n - 

RET ( - 

EXP: not affected 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

3 

NOT +C DAA 
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DAS 

Example: 



8 CONSTANT BCD# ( number of BCD digits ) 
BCD# ARRAY input2 
BCD# ARRAY inputl 

: DIG- ( digit count LSD_Addr -- ) 

Y! SWAP DAS SWAP ( generate 9's complement ) 

#DO ( digit count -- digit ) 

[Y] @ + DAA [Y-]! 1 0 ( transfer CARRY on stack ) 

-7LEAVE ( exit LOOP if NOT CARRY ) 

#LOOP ( repeat until index = 0 ) 

DROP ( skip TOS overflow digit ) 



: BCD- ( count LSD_Addr1 LSD_Addr2 - ) 

Y! X! SET_BCF ( set CARRY and pointer registers ) 
#DO 

[Y]@ [X-]@ DAS ( 9's complement generation ) 
+ DAA [Y-]! 
#LOOP 



Calculate 

BCD# Input2 [7] Inputl [7] BCD- ( Inp1 :=lnp1-lnput2 ) 

3 BCD# Inputl [7] DIG- ( Inputl := Inputl - 3 ) 
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DECR 



4.8.94 Dec-R 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Decrements the lowest nibble (i.e. the loop index) on the 
Return Stack. 

Assembler instruction 

1C hex 

EXP ( - ) 

RET ( u | u | n -- u | u I n-1) 

EXP: not affected 

RET: not affected 

CARRY flag not affected 

BRANCH flag = set, if (n-1 <> 0) 

Not affected 

1 

#DO .. #LOOP (#LOOP uses DECR) 
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q FORTH Language Dictionary 



DECR 

Example 1 : 



: DECR_Example 
3 >R 



DECR 


( RET stack: 


u 


u 


3 -- u I 


u 


2 & B flag 


DROP 


( EXP stack: 




2 -- 








DECR 


( RET stack: 


u 


u 


2 -- u | 


u 


1 & B flag 


DECR 


( RET stack: 


u 


u 


1 -- u I 


u 


0 no flag 


DECR 


( RET stack: 


u 


u 


0 -- u I 


u 


F & B flag 


DECR 


( RET stack: 


u 


u 


F - u | 


u 


E & B flag 


DECR 


( RET stack: 


u 


u 


E - u | 


u 


D & B flag 


DECR 


( RET stack: 


u 


u 


D - u 


u 


C & B flag 



DROPR ( pop "one element" from return stack 



Example 2: 

Library implementation: of #LOOP : 

( Purpose: #LOOP - macro is used to terminate a #DO loop. 
( On each iteration of a #DO loop, #LOOP decrements the 
( loop index on the Return Stack. It then compares the index 
( to zero and determines whether the loop should terminate. 
( If the new index is decremented to zero the loop is 
( terminated and the loop index is discarded from the Return 
( Stack. Otherwise, control jumps back to the point just after 
( the corresponding start of the #DO macro. 
\ IF lndex-1 > 0 

\ THEN RET ( u I u I Index -- ulullndex-1 

\ ELSE RET ( u | u | Index -- 



CODE #LOOP DECR 

BRA _$#DO 
_$LOOP: DROPR 
END-CODE 



(RET: u I u I Index -- ulullndex 
( IF Index > 0, loop again 
( forget index on return stack 
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4.8.95 DEPTH 



DEPTH 

Purpose: 
Category: 



Leaves the currently used depth of the Expression Stack on 
top of the stack. 

Stack operation/interrupt handling/qFORTH colon 
definition 



Library Implementation: : DEPTH SP@ SO D- ( -- SPh SPI SOh SOI -- diff ) 

NIP 1- ( diff — n ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (~n) (n<=Fh) 
RET ( - ) 

EXP: 1 element will be pushed onto the stack 

RET: not affected 

CARRY flag affected 

BRANCH flag set, if (depth = 0) 

Not affected 

9 

RFREE RDEPTH 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-212 



4747A-4BMCU-01/04 
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Example: 



DEPTH 



depth-ex 
depth 

1 2 

DEPTH 

34 

DEPTH 

2DR0P 2DR0P 
2DR0P DROP 



( [*1]-5 

( 5 -- 5 1 2 

( 5 1 2 -- 5 1 2 8 

( 5128 -- 512834 

( 5 1 2 8 3 4 ~[*1] 5 1 2 834 b 

( drop the 4 nibbles and 

( the 3 result values. 
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q FORTH Language Dictionary 



Dl 



4.8.96 Disable-lnterrupt or Purpose: 
D-l 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Disable execution of higher prioritized interrupts until the 
next El or RTI instruction is performed. The access to 
semaphores, variables or peripheral resources by 
differently prioritized interrupt routines will require a DI/EI 
sequence. 

Note: The generation of interrupts and latching in the 
interrupt pending register is not disabled. 

Interrupt handling/assembler instruction 

1A hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

LENABLE flag reset 

CARRY and BRANCH flags are not affected 

Not affected 

1 

El RTI INTO .. INT7 SWIO .. SWI7 
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Dl 



Example: 

Library implementation: of ROLL: 
: ROLL 

?DUP 

IF 

CCR@ Dl >R 
1+ PICK>R 



1 M+X! 

#DO [+X]@ [+Y]! #LOOP 
DROP R> 
R> CCR! 
ELSE DROP THEN 



( save current l-flag setting on RET st. ) 
( do a PICK, move PICKed value on RET st.) 
( move ptr from Y -> X reg. ) 
( adjust X reg. pointer ) 
( shift data values one down ) 



( restore l-flag setting in CCR 



) 
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DMAX 



4.8.97 D-max 



Purpose: 
Category: 

Library Implementation: 

: DMAX 



DMAX3: 



_DMAX1 : 
DMAX2: 



Leaves the greater of two 8-bit unsigned values on the stack. 



Stack operation 



2>R 

2DUP 

2R@ 

ROT 

2>R 

OVER 

CMP_LT 

BRA _DMAX1 

<> 

BRA _DMAX3 
2R@ 

< 

BRA _DMAX2 

DROPR 

2DROP 

2R> 

EXIT 

2DROP 

DROPR 

DROPR 

[ E -2 R 0 ] 



double-length)/qFORTH colon definition 

will be improved/changed soon; using 
D<= D> 

d1 d2 -- d1 

d1 --d1 d1 

d1 d1 -- d1 d1 d2 

d1 d1h d1l d2h d2l -- d1 d1h d2h d2l d1l 

d1 d1h d2h d2l d1l -- d1 d1h d2h 

d1 d1hd2h -d1 d1hd2hd1h 

d1 d1h d2h d1h-d1 d1h d2h[B-flag] 

jump if d2 < d1 in higher nibble 

d1 d1h d2h -- d1 [BRANCH flag] 

jump if d2 > d1 in higher nibble 

d1 -- d1 d2l d1l 

d1 d2l d1 1 — d1 

jump, if d2l < d1l 

skip compares values from RET stack 
d1 -- 
- d2 

skip compares values from EXP stack 

skip values from RET stack 

-d1 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Register: 
Bytes Used: 

See Also: 



IF d1 >d2 
THEN EXP 
ELSE EXP 
RET 



(d1 d2 -d1 
( d1 d2 -- d2 
(-- 



EXP: 2 elements will be popped from the stack 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 
30 

DMIN MAXMIN 
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DMAX 

Example: 

: DMAX-Example 
ABh 25h DMAX 2DR0P ( - A B 2 5 - A B -) 

ABh ABh DMAX 2DR0P ( -- A B A B -- A B --) 

25h ABh DMAX 2DR0P ( -- 2 5 A B - A B --) 
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DMIN 



4.8.98 D-min 



Purpose: 
Category: 

Library Implementation: 



DMIN 



Leaves the smaller of two 8-bit unsigned values on the stack. 



Stack operation 



_DMIN3: 



_DMIN1: 
DMIN2: 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



double-length)/qFORTH colon definition 





( will be improved/changed soon; using 




D<= D> 


Z>H 


( 01 " 0\ 


2DUP 


(d1 --d1 d1 


2R@ 


( d1 d1 -- d1 d1 d2 


ROT 


( d1 d1h d1l d2h d2l -- d1 d1h d2h d2l d 


2>R 


( d1 d1h d2h d2l d1 1 — d1 d1h d2h 


OVER 


(d1 d1hd2h --d1 d1hd2hd1h 


CMP_GT 


( d1 d1h d2h d1h -- d1 d1h d2h 




[BRANCH flag] 


BRA _DMIN1 


( jump if d2 < d1 in higher nibble 


<> 


( d1 d1 h d2h -- d1 [BRANCH flag] 


BRA _DMIN3 


( jump if d2 > d1 in higher nibble 


2R@ 


( d1 -- d1 d2l d1l 


> 


(d1 d2ld1l-d1 


BRA _DMIN2 


(jump if d2l < d1l 


DROPR 


( skip compares values from RET stack 


2DROP 


( dl — 


2R> 


( -- d2 


EXIT 




2DROP 


( skip compares values from EXP stack 


DROPR 


( skip values from RET stack 


DROPR 


(-d1 


[ E -2 R 0 ] 




IF d1 <d2 




THEN EXP 


( d1 d2 - d1 ) 


ELSE EXP 


( d1 d2 -- d2 ) 


RET 


(-- ) 



EXP: 2 elements are popped from the stack 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

30 

DMAX MIN MAX 
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DMIN 

Example: 

: DMIN-example 
ABh 25h DMIN 2DR0P ( -- A B 2 5 -- 2 5 -- ) 

25h 25h DMIN 2DR0P ( --2525-25-- ) 

25h ABh DMIN 2DR0P ( - 2 5 A B - 2 5 - ) 
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4.8.99 D-negate 



DNEGATE 



Purpose: 
Category: 



2's complement of the top 8-bit value. 
Arithmetic/logical(double-length)/qFORTH colon definition 



Library Implementation: : DNEGATE 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



0 SWAP - 
0 ROT -c 
SWAP ; 
( d -- -d 
(-- 



( dh dl -- dh -dl 
( dh -dl -- -dl -dh 



( -dl -dh - -d 



) 



EXP 

RET (- ) 

EXP: not affected 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

8 

NEGATE 
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DNEGATE 

Example: 

1 CONSTANT true 
0 CONSTANT false 



D_Negate 
18h 12h D- 
12h DNEGATE 18h 
D+ 

D= IF true 
ELSE false 
THEN 



( 18h - 12h = 06h 

( 2's complement of 12h add to 18h 
( 18h + [-12h] = 06h ? 
( is the result equal ? 
( 'true' = 1 = YES ! 
( end of test: return. 
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4.8.100 DO 



DO 



Purpose: 



Category: 



Indicates the start of an iterative loop. 

DO is used only within a colon definition and only in a pair 
with LOOP or +LOOP. The two numbers on top of the stack, 
at the time DO is executed, determine the number of times 
the loop repeats. 

The topmost number on the stack is the initial loop index. The 
next number on the stack is the loop limit. The loop 
terminates when the loop index is incremented past the 
boundary between limit-1 and limit (if limit is reached). 

A DO loop is always executed at least once, even if the loop 
index initially exceeds the limit. 

Control structure/qFORTH macro 



Library Implementation: CODE DO 

2>R 



_$DO: [ E -2 R 1 ] 



( EXP: limit index -- 
( RET: -- ullimitlindex 
(DO LOOP backpatch 
label 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 

EXP 

RET 



( limit index 
( -- u | limit | 



index) 



EXP: 2 elements will be popped from the stack 

RET: 1 element (2 nibbles) will be pushed onto the stack 

Not affected 

Not affected 

1 

LOOP #DO #LOOP ?DO +LOOP ? LEAVE -7LEAVE 
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Example: 



DOl 



DoLoop 
62 
DO 

I 

TestPortl OUT 
LOOP 

92 
DO 

I 

TestPortl OUT 
2 +LOOP 



limit and start on the stack. 

copy the index from the Return Stack, 
write 2, 3, 4, 5 to the TestPortl'. 
loop until limit = index. 



write 2, 4, 6, 8 to the TestPortl'. 
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DROP 



4.8.101 DROP 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Removes one 4-bit value from the top of the Expression 
Stack, i.e., decrements the Expression Stack pointer. 

Stack operation (single-length)/assembler instruction 

2E hex 

EXP ( n1 — ) 

RET ( - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

Not affected 

Not affected 

1 

2DROP 3DROP 
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q FORTH Language Dictionary 



Example: 



DROP 



DROP_Example 
19H 
1 1 H 
DROP 
2DROP 
19h 

3DROP 



-- 1 9 

1 9 -- 1 9 1 1 
1 9 1 1 -- 1 9 1 
1 9 1 -- 1 
1 -- 1 1 9 
119- 
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DROPR 



4.8.102 DROP-R 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Decrements the Return Stack pointer. Removes one entry 
(= 3 nibbles) from the Return Stack. 

Assembler instruction 

2F hex 

EXP ( - ) 

RET ( x | x | x—) 

EXP: not affected 

RET: 1 element (12-bits) is popped from the Return Stack 
Not affected 
Not affected 
1 

>R I R> 2>R 2R> 3>R 3R> EXIT 
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DROPR 



Example 1 : 



: DROPR_Example 



1 2 3 3>R 



( RET: -- 1 | 2 | 3 ) 



DROPR 



( RET: 1 | 2 | 3 -- ) 



Example 2: 

Library implementation: of #LOOP : 

( #LOOP - Macro ) 

( Purpose: #LOOP is used to terminate a #DO loop. ) 

( ) 

( On each iteration of a #DO loop, #LOOP decrements the ) 

( loop index on the return stack. It then compares the index ) 

( to zero and determines whether the loop should terminate. ) 

( If the new index is decremented to zero, the loop is ) 

( terminated and the loop index is discarded from the return ) 

( stack. Otherwise, control jumps back to the point just after ) 

( the corresponding start of the #DO macro. ) 

\ IF lndex-1 > 0 

\ THEN RET ( u I u I Index -- u I u I lndex-1 

\ ELSE RET ( u | u I Index - 

CODE #LOOP DECR ( RET: u I u I Index -- u I u I Index 



BRA 



.$#DO 



( IF Index > 0, Loop again 
( forget Index on RET stack 



$LOOP: DROPR 



[E0R-1 ] 



END-CODE 



MARC4 4-bit Microcontrollers Programmer's Guide 



ill nEL 

^^^^^^^ 




4-227 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.8.103 D-TABLE-fetch 



D TABLE 



Purpose: 



Category: 



Fetches an 8-bit constant from a ROMCONST array, whereby the 
12-bit ROM address and the 4-bit index are on the EXP stack. 



Memory operation (double-length)/qFORTH colon definition 



Library Implementation: 



DTABLEt 



M+ 
IF 

ROT 1+ <ROT 

THEN 

3>R 

TABLE 



[E-2 RO] 



( ROMh ROMm ROMI ind 
ROMI' ) 



ROMh ROMm' 



( on overflow propagate CARRY 

( ROMh ROMm' ROMI' -- ROMh' 
ROMm' ROMI' 

( move TABLE address to RET stack 

( -- consthigh constlow 

( TABLE returns directly to the CALLer 
during microcode execution. 

( therefore 'EXIT' is not necessary 



) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (ROMh ROMm ROMI index - consth constl ) 

RET ( - ) 

EXP: 2 elements will be popped from the stack 

RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

14 

TABLE ROMByte® ROMCONST 
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DTABLE® 



Example: 



ROMCONST DigitTable 



10h , 1 , 2 , 3 , 4 , 45h , 6 , 7 , 8, 
9, Ah , Bh , Ch , Dh , Eh , OFh , 



D_Table@ 
0 0 1 ROMByte® 
2DROP 

DigitTable 5 
DTABLE® 2DROP 

DigitTable 1 
DTABLE® 2DROP 

DigitTable 0 
DTABLE® 2DROP 

DigitTable Fh 
DTABLE® 2DROP 



fetch byte at address 001 h : OFh = SLEEP ) 
and delete it. 
sixth byte of the table: 
put address and index on the stack, 
fetch and delete the value : 45h . 
second byte of the table: 
put address and index on the stack, 
fetch and delete the value : 01 h . 
first byte of the table and min. index : 
put address and index on the stack, 
fetch and delete the value : 10h . 
last byte of the table and max. index : 
put address and index on the stack, 
fetch and delete the value : OFh. 
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4.8.104 D-TOGGLE 



DTOGGLE 



Purpose: 
Category: 

Library Implementation: 



TOGGLES [exclusive ors] a byte at a given address with a 
specified bit pattern. The address of the 8-bit variable is on 
top of the Expression Stack. 

Memory operation (double-length)/qFORTH colon definition 



: DTOGGLE Y! 
[+Y]@ XOR 
[Y-]! 

[Y]@ XOR 
[Y]l 



( d addr - nh nl 
( nh nl -- nr rl' 



( nh 
(rT- 



rl' 



) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (daddr- ) 

RET (- ) 

EXP: 4 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag set, if higher nibble gets zero 

The contents of the Y register are changed 

8 

TOGGLE XOR 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-230 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



DTOGGLE 



Example: 



2VARIABLE Supra 
VARIABLE 1 Supra 
: D_Toggle 

0 0 Supra 2! 

FFh Supra DTOGGLE 

FFH Supra DTOGGLE 

AAh Supra 2! 

55h Supra DTOGGLE 

5 1 Supra ! 

3 1 Supra TOGGLE 

Fh 1 Supra ! 

Fh 1 Supra TOGGLE 

Fh 1 Supra TOGGLE 



reset in the RAM two nibbles to OOh. 

OOh XOR FFh = FFh 

flags: no BRANCH 

OOh XOR FFh = OOh 

flags: BRANCH 

set the two nibbles to AAh. 

1010 1010XOR 0101 0101 =1111 1111 

flags: no BRANCH 

set in the RAM one nibble to 01 01 . 

truth table: 01 01 XOR 001 1 = 01 1 0 

flags: no BRANCH 

set in the RAM one nibble to Fh. 

1111 XOR 1111 = 0000 

flags: BRANCH 

0000 XOR 1111=1111 

flags: no BRANCH 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-231 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



4.8.105 Doop 



DUP 

Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Duplicate the 4-bit value on top of the stack. 

Stack operation (single-length)/assembler instruction 

2D hex 

EXP ( n1 — n1 n1 ) 

RET ( - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

1 

2DUP3DUP DROP 
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DUP 



Example: 

: ONE-DUP 

9 ( - 9 ) 

5 ( 9 -- 9 5 ) 

DUP (95-955 ) 

3DROP (955- ) 
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El 



4.8.106 Enable-lnterrupt or 
E-l 



Purpose: 



Category: 



Sets the INTERRUPT_ENABLE flag in the condition code 
register. Use EI/DI only, if different tasks use the same 
resources; i.e. two tasks both use a peripheral EEPROM or 
RAM - without semaphore handling. 

Note: Under normal circumstances, the programer will not need 
to disable or enable interrupts - every task will have just the 
right interrupt level. 

Interrupt handling/qFORTH macro 



Library Implementation: CODE El 

LIT 1 CCR! 



( set LENABLE flag ) 



Stack Effect: 



Stack Changes: 



Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 
EXP ( - ) 

RET ( - ) 

EXP: not affected 
RET: not affected 
CARRY flag reset 
BRANCH flag reset 
LENABLE flag set 
Not affected 
2 

Dl RTI INTO .. INT7 SWIO 



SWI7 
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El 

Example: 

: lnterruptFlagRe_Set 
Dl ( disable the interrupt flag - CCR: x-x- ) 

5 ROLL ( re-order EXP stack values. ) 

El ( enable the interrupt flag - CCR: x-xl ) 
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4.8.107 ELSE 



ELSE 



Purpose: 



Category: 
Library Implementation: 

CODE ELSE SET_BCF 
(S)BRA _$THEN 



Part of the IF ... ELSE ... THEN control structure. ELSE, like 
IF and THEN may be used only within a colon definition. Its 
use is optional. ELSE executes after the TRUE part following 
the IF construct. If the condition is true ELSE forces 
execution to skip over the following FALSE part and resumes 
execution following the THEN construct. If the condition is 
false the FALSE block after the ELSE instruction will be 
executed. 

Control structure/qFORTH macro 



( set BRANCH&CARRY flag, FORCE jump) 
( to end of IF statement ) 



_$ELSE: 
END-CODE 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



[EO RO] 

EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 

CARRY and BRANCH flags are affected 
Not affected 
2-3 
IF THEN 
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Example: 



ELSE 



IfElseThen 
1 2 <= 
IF 

1 

ELSE 
0 

THEN 

1 2 > 
IF 

DROPO 
THEN 

1 2 > 
IF 

0 

ELSE 
1 

THEN 2DROP 



is 1 <= 2 ? 

yes, so the If block will be executed, 
a 1 will be pushed onto the stack. 

true => no execution of the ELSE block. 

is 1 > 2 ? 

false: nothing will be executed. 



is 1 > 2 ? 

not true => no execution. 

in this case, the 

ELSE block will be executed 

the results from the Expression Stack. 
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END-CODE 



4.8.108 END-CODE 



Purpose: 
Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Terminates an 'in-line' CODE definition. 

Predefined data structure 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

CODE <-> ':' and ';' 
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END-CODE 

Example 1 : 

3 ARRAY ReceiveData ( 12-bit data item ) 

( CODE to shift right a 1 2-bit data word ) 

CODE ShiftRDBits 

ReceiveData Y! 

CLR_BCF ( clear the CARRY for first shift ) 

[Y]@ ROR [Y]! 

[+Y]@ ROR [Y]! ( rotate thru CARRY ) 

[+Y]@ ROR [Y]! 
END-CODE 



: Example 2: 

ReceiveData Y! 

5 [Y]! Ah [+Y]! 0 [+Y]! 

ShiftRDBits 



( start address to Y register. ) 
( shift 'ReceiveData' 1 bit right ) 
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4.8.109 End-CASE 



ENDCASE 



Purpose: 



Terminates a CASE ... OF ... ENDOF 
structure. 



ENDCASE 



Category: 

Library Implementation: CODE ENDCASE 

DROP ( n -- ) 



When it executes, ENDCASE drops the 4-bit CASE index 
value if it does not match any of the OF comparison values. 

The 'OTHERWISE' case may be handled by a sequence 
placed between the last ENDOF and ENDCASE. Please 
note, however, that a value must be preserved across this 
sequence so that ENDCASE can drop it. 

Control structure/qFORTH macro 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



_$ENDCASE: [ E -1 R 0 ] 
END-CODE 

EXP ( n - ) (if no match ) 
EXP ( -- ) (if matched, then not executed) 
RET (- ) 

EXP: 1 element will be popped from the stack 

RET: not affected 

Not affected 

Not affected 

1 

CASE OF ENDOF 
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ENDCASE 

Example: 



5 CONSTANT Keyboard 
1 CONSTANT Portl 

: ONE 1 Portl OUT ; ( write 1 to the 'Portl' ) 

: TWO 2 Portl OUT ; ( write 2 to the 'Portl ' ) 

: THREE 3 Portl OUT ; ( write 3 to the 'Portl ' ) 

: ERROR DUP Portl OUT ; ( dump wrong input to Portl ) 

( duplicate value for the following ENDCASE; it drops one n. ) 

: CASE-Example 

Key Board IN ( request 1 -digit keyboard input ) 

CASE ( depending of the input value, ) 

1 OF ONE ENDOF ( one of these words will be ) 

2 OF TWO ENDOF (activated. ) 

3 OF THREE ENDOF ( ) 
ERROR ( otherwise ... ) 

ENDCASE ( n -- ) 
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4.8.110 End-OF 



ENDOF 



Purpose: 



Part of the OF 
ENDCASE. 



ENDOF structure used within CASE 



When an OF comparison value matches the CASE index 
value, ENDOF transfers control to the word following 
ENDCASE. If there was no match, control proceeds with the 
word following ENDOF. 



Category: 



Library Implementation: CODE ENDOF 

(S)BRA 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Control structure/qFORTH macro 
SET_BCF 
$ENDCASE 
_$ENDOF: [ E0 R0] 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag Set 
BRANCH flag Set 
Not affected 
2-3 

ENDCASE CASE OF 
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ENDOF 

Example: 



5 CONSTANT Keyboard 
1 CONSTANT Portl 

: ONE 1 Portl OUT ; ( write 1 to the 'Portl' ) 

: TWO 2 Portl OUT ; ( write 2 to the 'Portl ' ) 

: THREE 3 Portl OUT ; ( write 3 to the 'Portl ' ) 

: ERROR DUP Portl OUT ; ( dump wrong input to the Portl ) 

( duplicate value for the following ENDCASE; it drops one n. ) 

: CASE-Example 

Key Board IN ( request 1 -digit keyboard input ) 

CASE ( depending of the input value, ) 

1 OF ONE ENDOF ( one of these words will be ) 

2 OF TWO ENDOF (activated. ) 

3 OF THREE ENDOF ( ) 
ERROR ( otherwise ... ) 

ENDCASE ( n -- ) 
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4.8.111 ERASE 



ERASE 



Purpose: 



Resets n digits in a block of memory (RAM) to zero. Whereas 
n is less than 1 6; if n is zero, then 1 6 nibbles of RAM is set to 
0. 



Category: Memory operation (multiple-length)/qFORTH colon definition 

Library Implementation: 

: ERASE <ROT Y! ( addr count -- count ) 

0[Y]!1- ( count - count- 1 ) 

#DO 

0 [+Y]! 

#LOOP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( addr n -- ) 
RET ( - ) 

EXP: 3 elements are popped from the stack 
RET: not affected 
CARRY flag not affected 
BRANCH flag Reset 

The contents of the Y register will be changed 
14 

FILL CONSTANT ARRAY 
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ERASE 

Example: 



6 CONSTANT #Nibbles ( #_of_valid_bits ) 

0 CONSTANT #16 

3 CONSTANT TwoLgth 

#Nibbles ARRAY RamData ( nibble array with 6 elements 

and index from [0].. [5] ) 

1 6 ARRAY ShortArray ( index from [0] . . [1 5] ) 

TwoLgth 2ARRAY TwoArray ( this array includes bytes ) 

20 2LARRAY TwoLongArray 

: ClearArrays 

RamData #Nibbles ERASE ( initialize the data array ) 

ShortArray #1 6 ERASE ( 'delete' 1 6 nibbles ) 

TwoArray TwoLgth*2 ERASE ( set whole array to 0. ) 

TwoLongArray [4] 8 ERASE ( set byte [4] to [7] to 0. ) 

( for setting whole arrays with more than 16 nibbles to 0, ) 

( a special routine is required; or activate ERASE twice ! ) 
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EXIT 



4.8.112 EXIT 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Exits from the current colon definition. 

EXIT may be used in any of the following control structures: 

BEGIN ... REPEAT, 

IF ... THEN, 

CASE ... ENDCASE 

Note: EXIT may not be used inside of a DO loop 

For ending a colon definition, ';' is translated by the compiler 
to the EXIT instruction. 

Control structure/assembler instruction 

25 hex 

EXP ( - ) 
RET ( oldPC -- ) 
EXP: not affected 

RET: the return address (3 nibbles) is popped from the return 
stack into the program counter. 

Not affected 

Not affected 

1 

7LEAVE -7LEAVE ; RTI 
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EXIT 



Example 1 : 

: EXIT-Example 

62 3 ( --62 3 ) 

CMP_NE (623-62 ) 

IF SWAP EXIT ( if <> then EXIT else DROP TOS ) 

ELSE DROP (62-6 ) 
THEN 



Example 2: 

CODE Leave 

DROPR EXIT ( exits any DO .. LOOP ) 

END-CODE 

: Horizontal? ( example for leave DO .. LOOP ) 

DO ( col row - ) 

DUP I Pos@ = 

IF DROP 0 Leave [ R 0 ] THEN 
LOOP 
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4.8.113 Execute 



EXECUTE 



Purpose: 



Transfers control to the colon definition whose ROM code 
address is on the EXP stack. 



Category: Control structure 

Library Implementation: 

: EXECUTE 

3>R 
EXIT 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
See Also: 



EXP ( ROM addr - - ) 

RET ( - - ROM addr - - ) 

EXP: 3 elements are popped from the stack 

RET: 1 entry is used intermediately during execution 

CARRY flag not affected 

BRANCH flag not affected 

Not affected 
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EXECUTE 



Example: 



Dojncr 



DROPR 



\ Skip return address 



Time_count 1*! 



[N]; 

: Do_Decr 

DROPR 
Time_count 1-! 

[N]; 

: Do_Reset 

DROPR 

0 Time_Count ! 

[N]; 

Jump_Table 

Do_Nothing 
Do_lnrc 
Do_Decr 
Do_Reset 

;; AT FFOh \ Do not generate an EXIT 

: Exec_Example ( n - - ) 

>R ' Jump_Table R> 

2* M+ \ calculate vector address 

EXECUTE 
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FILL 



4.8.114 FILL 



Purpose: 
Category: 
Library Implementation: : FILL 



Fill a block of memory (n1 nibbles; 0 <= n1 <= Fh) with a 
specified digit (n2). 

Memory operation (multiple-length)/qFORTH colon 
definition 



2SWAP 
Y! DUP [Y]! 
SWAP 1 - 

#DO 

DUP [+Y]! 
#LOOP DROP 



( addr count n -- count n addr ) 
( count n addr ~ count n ) 
( count n -- n count-1 ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( addr n1 n2 -- ) 

RET ( - ) 

EXP: 4 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag reset 

The contents of the Y register are changed 

16 + '2SWAP' 

ERASE 
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FILL 

Example: 

8 CONSTANT Size 
Size ARRAY Digits 

: FilLExample 
Digits Size 3 
FILL 

34h Fh 5 FILL 
44h 0 6 FILL 



( -- address count data ) 

( fill array digits with 3 ) 

( RAM: 34h...42h - 15nibbles - will be 5. ) 

( RAM: 44h...53h - 1 6nibbles - will be 6. ) 
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R@ 



4.8.115 I 



R-Fetch 



Purpose: 



Category: 

Library Implementation: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Leaves (copies) the current #DO or DO loop index on the 
stack. 

If not used within a DO ... [+]LOOP, or #DO ... #LOOP, the 
value returned by I or R@ is undefined. 

Stack operation (single-length)/assembler instruction 

CODE R@ I END-CODE (macro of 'R@') 

23 hex 

EXP ( -- index ) 

RET ( u| limit/u| index -- u| limit/u| index) 

EXP: the current loop index will be pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

1 

J DO [+]LOOP #DO ... #LOOP 
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Example 1 : 



1 CONSTANT Portl 



R@ 



HASH-DO-LOOP 
14 #DO 

I Portl OUT 
#LOOP 



( loop 14 times 

( write data to 'Portl': E, D, C, 
( repeat the loop. 



1. 



Example 2: 



Error 
3R@ 
3#DO 
I OUT [ E 0 ] 
#LOOP [ E 0 ] 



( show program counter, where CPU fails. ) 



( write address to Port 1 , 2 and 3 



( suppress compiler warnings. 



RFetch 
1 3335 
3 >R 

< IF Error THEN 

< IF Error THEN 
R@ > IF Error THEN 
R@ <> IF Error THEN 
R> >= IF Error THEN 



( compare all these values with 3 

( move 3 to return stack 

( copy 3 from RET several times 

( 'Error' should never be called. 

( 

( 

( return stack gets original state 
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IF 



4.8.116 IF 



Purpose: 



Category: 

Library Implementation: 



Begins an IF ... ELSE ... THEN or IF ... THEN control 
structure. When IF is executed the BRANCH flag in the 
condition code register (CCR) determines the direction of the 
conditional branch. If the BRANCH flag is TRUE (set), the 
words between the IF and ELSE (or IF and THEN if no ELSE 
was compiled) are executed. If the BRANCH flag is false 
(= 0), and an ELSE clause exists, then the words between 
ELSE and THEN are executed. In either case, subsequent 
execution continues just after THEN. 

Control structure/qFORTH macro 



CODE IF TOG_BF 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



( complement B-Flag, FORCE 
jump if false ) 



(S)BRA _$ELSE ( to _ELSE / _THEN label 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag not affected 
BRANCH flag = NOT BRANCH flag 
Not affected. 
1 -3 

THEN ELSE 



) 
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Example: 



IF 



IfElseThen 
1 2 <= 
IF 

1 

ELSE 
0 

THEN 

1 2 > 
IF 

DROPO 
THEN 

1 2 > 
IF 

0 

ELSE 
1 

THEN 2DROP 



is 1 <= 2 ? 

yes, so the If block is executed, 
a 1 will be pushed onto the stack. 

true => no execution of the ELSE block. 

is 1 > 2 ? 

false: nothing will be executed. 



is 1 > 2 ? 

not true => no execution. 

in this case, the 

ELSE block is executed 

the results from the expression stack. 
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IN 



4.8.117 IN 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Read data from an I/O ports. 

Note: Before changing the direction of a bi-directional 

(nibble-wise I/O) port from output to input, first a value of 'Fh' 
should be written to that port. After power-on-reset, all 
bi-directional ports are switched to input. 

Stack operation/assembler instruction 

1B hex 

data ) 
) 



EXP ( port 
RET ( -- 
EXP: 



RET: 

CARRY flag 
BRANCH flag 
Not affected 
1 

OUT 



The port address is pulled from the stack; the 
'data' is pushed onto the stack. 

not affected 

not affected 

set, if port = 0 ! 
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IN 



Example 1 : 

1 CONSTANT Portl 
: CountDown 

15#DO ( 15 iterations ) 

I ( copy index from return stack. ) 

Portl OUT ( Index is output to the 'Portl ' ) 

#LOOP 



Example 2: 

: ReadPort ( port -- data ) 

Fh OVER OUT ( port - port Fh - p Fh p - p ) 

IN ( port -- nibble ) 
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INDEX 



4.8.118 INDEX 



Purpose: 



The qFORTH word INDEX performs RAM address 
computations during runtime to give the programmer the 
ability to access any element of an ARRAY, 2ARRAY, etc. 



Category: Predefined data structure/q FORTH macro 

Library Implementation: Different routines are available for ARRAY, 2ARRAY, 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



) for ARRAY, 2ARRAY 
) for LARRAY, 2LARRAY 



EXP ( n d -- d 
EXP ( d d -- d 
RET ( - ) 

EXP: 1/2 element(s) will be popped from the stack 

RET: not affected 

CARRY flag reset 

BRANCH flag = CARRY flag 

Not affected 

Uses 'D+' or 'M+' 

@ I ARRAY 2ARRAY LARRAY 2LARRAY 
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INDEX 

Example: 

10 ARRAY 10 Nibbles 

: IndexExample ( write 1 .. 10 into the array [0] .. [9] ) 

10 #DO 

I ( copy values for writing: A, 9, 8, ... 1 ) 

I 1- 10Nibbles INDEX ! 
#LOOP ( subtract 1 from index for [9] .. [0] ) 
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'INTO ... INT7' 



4.8.119 Int-Zero ... Int-Seven Purpose: 

The interrupt routines can be activated by external hardware or by internal software 
interrupts (SWT). These predefined HARDWARE/SOFTWARE interrupt service routines 
are placed at the following fixed addresses by the compiler: 



Interrupt 


Priority 


ROM Address 


Interrupt Opcode 
(Acknowledge) 


Size 
(Bytes) 


INTO 


lowest 


040h 


C8h (SCALL 040h) 


64 


INT1 




080h 


DOh (SCALL 080h) 


64 


INT2 




OCOh 


D8h (SCALL OCOh) 


64 


INT3 




100h 


EOh (SCALL 100h) 


64 


INT4 




140h 


E8h (SCALL 140h) 


64 


INT5 




180h 


FOh (SCALL 180h) 


64 


INT6 




1C0h 


F8h (SCALL 1C0h) 


32 


INT7 


highest 


1E0h 


FCh (SCALL 1 EOh) 


unlimited 



During runtime the PC is set by the interrupt logic to the addresses determined by the 
compiler. If an interrupt routine gets too long, then the compiler will not be able to place 
this routine in the corresponding segment. To avoid this problem, it may be necessary to 
divide the routine and define parts of it as new colon definitions, which will be placed at 
other free ROM gaps. For more information about interrupts, please have a look in the 
other manuals. 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



Interrupt handling 
EXP ( - ) 

RET ( -- [old PC] ) on runtime 
EXP: not affected 

RET: 1 entry (old PC) is pushed onto the stade 

Will be saved on entry; the @ (fetch) and ! (store) instructions 
(X@ Y@ CCR@...) will be inserted in the opcode automati- 
cally by the compiler - if necessary. 

If the compiler directive "$OPTIMIZE - SAVECONTXT" is 
used, all needed register must be saved manually. 

Not affected 

0 

SWIO .. SWI7 RTI $AUTOSLEEP 
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'INTO ... INT7' 

Example: 

: INT5 

CCR@ Y@ X@ ( instructions will be inserted by the compiler 

automatically ) 

IncTime ( activate the time-increment module every 125 ms ) 

X! Y! CCR! ( store the register data back automatically ) 

; ( an RTI will occur in the opcode. ) 
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4.8.120 J 



Purpose: 



Leaves the loop index of the next outer DO or #DO loop on 
the stack when used within a nested loop. 



If not used within two DO ... [+]LOOP, or #DO ... #LOOP, the 
value returned by J is undefined. 

Category: Stack operation (single-length)/qFORTH macro 

Library Implementation: CODE J 



( -- limit I 
( limit I -- limit I J 
( limit I J -- J limit I 
( J limit I -- J 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



2R> ( -- limit I ) 

I 

<ROT 
2>R 
END-CODE 

EXP ( -J ) 

RET (u| limit | J u| limit | l--u| limit | J u| limit I I) 

EXP: 1 element will be pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

6 

I DO ... [+]LOOP #DO ... #LOOP 
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Example: 

1 CONSTANT Portl 



HASH-DO-LOOP 
6#DO 

I Portl OUT 
2#DO 

J Portl OUT 
#LOOP 
#LOOP 



( loop 6 times 

( write to 'Portl': 6, 5, 4, 1. 

( loop 2 times in the loop 

( get index from outer loop. 

( repeat the loop 2 times. 

( repeat the loop 6 times. 

( Portl - result: 6, 6, 6, 5, 5, 5, 4, ... 2, 1 , 1 , 1 
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LARRAY 



4.8.121 Long-ARRAY 



Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Allocates RAM space for storage of a long single-length 
(4-bit) array, using an 8-bit array index value. Therefore, the 
number of 4-bit array elements can be greater than 1 6. 

The qFORTH syntax is as follows: 

<number> LARRAY <identifier> [ AT <RAM-Addr> ] 

At the time of compilation, LARRAY adds <name> to the 
dictionary and ALLOTs memory for storage of <number> 
single-length values. At execution time, <name> leaves the 
RAM address of the parameter field ( <name> [0] ) on the 
expression stack. 

The storage ALLOTed by an LARRAY is not initialized; see 
ERASE. 

Predefined data structure 

EXP ( - n ) a fetch (@) on runtime 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

0 

2 ARRAY ARRAY 2 LARRAY Index ERASE 
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LARRAY 

Example: 

12 ARRAY ShortArray ( normal array example. ) 

64 LARRAY LongArray AT 68h 

: ArrayExample 

ShortArray [ShortArray Length] ERASE ( set all 12 nibbles to 0 ) 

7 LongArray [12] I 

8 #DO 0 0 LongArray 0 11-2* 

M+2! 

#LOOP 
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4.8.122 LOOP 



LOOP 



Purpose: 



Category: 



LOOP may be used to terminate either DO or ?DO loops. 

On each iteration of a DO loop, LOOP increments the loop 
index. It then compares the index to the loop limit to 
determine whether the loop should terminate. If the new 
index is incremented across the boundary between limit-1 
and limit, the loop is terminated and the loop control 
parameters are discarded. Otherwise, control jumps back to 
the point just after the corresponding DO. 

Control structure/qFORTH macro 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



CODE LOOP 


2R> 


( -- limit index 




INC 


( limit index -- limit index' 




OVER 


( limit index' -- limit index' limit 




CMP_LT 


( limit index' limit ~ limit index' 




2>R 


( limit index' -- 




BRA _$DO 


( IF Index < limit, loop again 


_$LOOP: 


DROPR 


( forget limit, index on RET 
stack 


[EOR-1 ] 






END-CODE 






EXP 




) 



u I Limit | lndex+1 ) 

) 



IF lndex+1 < Limit 

THEN RET ( u| Limit | Index 

ELSE RET ( u| Limit | Index 

EXP: not affected 

RET: IF lndex+1 = Limit THEN 

1 element (3 nibbles) will be popped from the stack 

CARRY and BRANCH flags are affected 

Not affected 

9 

DO #DO #LOOP +LOOP 
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Example: 



LOOP 



: DoLoop 
62 
DO 

I 

TestPortl OUT 
LOOP 
92 
DO 

I 

TestPortl OUT 
2 +LOOP 



( limit and start on the stack. 
( 

( copy the index from the Return Stack. 
( write 2, 3, 4, 5 to the TestPortl'. 
( loop until limit = index. 

( 

( 

( write 2, 4, 6, 8 to the TestPortl'. 

( 
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4.8.123 M-plus 



M+ 



Purpose: 



M+ adds the digit (4 bit) on top of the data stack to the 8-bit 
value below that. 



Category: Arithmetic/logical (double-length)/FORTH colon definition 

Library Implementation: : M+ 

+ SWAP 0 +c SWAP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 n - d2 ) 

RET ( - ) 

EXP: 1 element is popped from the stack. 

RET: not affected 

CARRY flag set on arithmetic overflow 
BRANCH flag = CARRY flag 
Not affected 
5 

D- D+ D2* D2/ M- 
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M+ 

Example: 



MPIusMinus 
13h5 M+ 

5 M- 
2DR0P 
13h 15 M+ 
2DR0P 
FCh9 M+ 

9 M- 
2DR0P 



13h + 5 = 18h CARRY: % BRANCH: % 
18h - 5 = 13h CARRY: % BRANCH: % 
two nibbles. 

13h +15 = 22h CARRY: % BRANCH: % 
two nibbles. 

FCh + 9 = [105h]05h CARRY: 1 BRANCH: 1 
05h - 9 = FCh CARRY: 1 BRANCH: 1 
two nibbles. 
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4.8.124 M-minus 



M- 



Purpose: 



M- subtracts a nibble on the data stack from the 8-bit value 
below that. 



Category: Arithmetic/logical (double-length)/FORTH colon definition 

Library Implementation: : M- 

- SWAP 0 -c SWAP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d1 n - d2 ) 

RET ( - ) 

EXP: 1 element is popped from the stack. 

RET: not affected 

CARRY flag set on arithmetic underflow 
BRANCH flag = CARRY flag 
Not affected 
5 

D- D+ D2* D2/ M+ 
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M- 



Example: 

: MPIusMinus 



13h 5 M+ ( 13h + 5 = 18h CARRY: % BRANCH: % 

5 M- ( 18h - 5 = 13h CARRY: % BRANCH: % 

2DR0P ( two nibbles. 

13h 15 M+ ( 13h +15 = 22h CARRY: % BRANCH: % 

2DROP ( two nibbles. 

FCh 9 M+ ( FCh + 9 = [1 05h]05h CARRY: 1 BRANCH: 1 

9 M- ( 05h - 9 = FCh CARRY: 1 BRANCH: 1 

2DROP ( two nibbles. 
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MAX 



4.8.125 MAX 



Purpose: 
Category: 



Leaves the greater of two 4-bit values on the stack. 
Comparison (single-length)/qFORTH colon definition 



Library Implementation: : MAX 



BRA LESS 



LESS: 



OVER 
CMP_LT 

SWAP 
DROP 
[E-1R0] 



( n1 n2 - n1 n2 n1 

( n1 n2 n1 -- n1 n2 [BRANCH flag] 

( jump if n1 < n2 

( n1 n2 - n2 n1 

( leave max number on stack 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Register: 
Bytes Used: 
See Also: 



( n1 n2 -- n1 ) 
( n1 n2 -- n2 ) 
(-- ) 



IF n1 > n2 
THEN EXP 
ELSE EXP 
RET 

EXP: 1 element will be popped from the stack 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

7 

MIN DMAX DMIN 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-272 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



Example: 



MAX 



Min_Max 
Ah 2 MIN DROP 
2 2 MIN DROP 
2 Ah MIN DROP 
Ah 2 MAX DROP 
Ah Ah MAX DROP 
2 Ah MAX DROP 



A 2 - 2 -- flags: CARRY - 

2 2 -- 2 -- flags: - - 

2 A -- 2 -- flags: - BRANCH 

A 2 -- A -- flags: CARRY BRANCH 

A A- A- flags: - - 

2 A- A- flags: - - 
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MIN 



4.8.126 MIN 



Purpose: 
Category: 

Library Implementation: 



Leaves the smaller of two 4-bit values on the stack. 
Comparison (single-length)/qFORTH colon definition 



MIN 



BRA 



GREAT: 



OVER 
CMP_GT 

_GREAT 
SWAP 
DROP 
[E-1R0] 



( n1 n2 - n1 n2 n1 

( n1 n2 n1 -- n1 n2 
[BRANCH flag] 

( jump if n1 > n2 

( n1 n2 -- n2 n1 



) 



( leave max number on stack ) 



Stack Effect: 



Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



IF n1 < n2 

THEN EXP (n1n2»n1 
ELSE EXP ( n1 n2 -- n2 

RET ( -- 

EXP: 1 element will be popped from the stack 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

7 

MAX DMIN DMAX 
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Example: 



MIN 



Min_Max 
Ah 2 MIN DROP 
2 2 MIN DROP 
2 Ah MIN DROP 
Ah 2 MAX DROP 
Ah Ah MAX DROP 
2 Ah MAX DROP 



A 2 - 2 -- flags: CARRY - 

2 2 -- 2 -- flags: - - 

2 A -- 2 -- flags: - BRANCH 

A 2 -- A -- flags: CARRY BRANCH 

A A- A- flags: - - 

2 A- A- flags: - - 
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4.8.127 MOVE 



MOVE 



Purpose: 



Category: 

Library Implementation: 



Copies an array of digits from one memory location to 
another. 

Number of nibbles n : 2 <= n <= Fh (0 moves 16 nibbles) 

The digit at the LOWEST memory location is copied first 
[unlike 'MOVE>']. This allows the transfer of data between 
overlapping memory arrays from a higher to a lower address. 

Memory operation (multiple-length)/qFORTH colon definition 

: MOVE 

Y! X! ( length SrcAddr DestAddr -- ) 

[X]@ [Y]! ( Move 1st element ) 

1-#DO [+X]@ [+Y]I #LOOP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( n from to -- ) 

RET ( - ) 

EXP: 5 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag reset 

Both the X and Y index registers will be affected 
14 

MOVE> FILL ERASE 
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Example: 



16 ARRAY A1 6 AT 40h 



MOVE 



Move Array 
A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4 A16 A16 [12] 
MOVE 

( same result, as with: 
A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4A16[7] A16[5] 
MOVE 

A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4A16[5] A16[7] 
MOVE 



( write 0 ... Fh to RAM; start at 40h ) 

( repeat 16 times: copy index to RAM. 
( with start address and pre-increm.:o.k. 
( 4 nibbles are moved 12 nibb's backwards 
'4 A16[3]A16[15] MOVE>' ! 
( write 0 ... Fh to RAM; start at 40h 

( repeat 16 times: copy index to RAM. 
( with start address and pre-increm.: o.k. 
( 4 nibbles are moved 2 nibbles backwards 
( write 0 ... Fh to RAM; start at 40h 

( repeat 16 times: copy index to RAM. 
( with start address and pre-increm.: 
( ERROR: overwriting of the source array. 
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4.8.128 MOVE-greater 



MOVE> 



Purpose: 



Category: 

Library Implementation: 



Copies an array of digits from one memory location to 
another. 

Number of nibbles n : 2 <= n <= Fh (0 moves 16 nibbles) 

The digit at the HIGHEST memory location is copied first 
[unlike 'MOVE']. This allows the transfer of data between 
overlapping memory arrays from a LOWER to a HIGHER 
address. 

Memory operation (multiple-length)/qFORTH colon definition 
: MOVE> 

Y! X! ( length SrcAddr DestAddr -- ) 

#DO [X-]@ [Y-]! #LOOP 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Register: 
Bytes Used: 
See Also: 



EXP ( n from to -- ) 

RET ( - ) 

EXP: 5 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag reset 

Both the X and Y index registers are affected 
10 

MOVE FILL ERASE 
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MOVE> 



Example: 



16 ARRAY A1 6 AT 40h 



Move Array 

( an array is used: start at 40h; end at 4Fh, with O...Fh. 



A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4A16[6] A16[9] 
MOVE> 
A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4A16[9] A16[6] 
MOVE> 
A16 [15] Y! 0 
#DO I 1- [Y-]! 
#LOOP 

4A16[3] A16[15] 
MOVE> 



( write 0 ... Fh to RAM; start at 40h 

( repeat 16 times: copy index to RAM. 
( with end address / post-decrement: o.k. 
( 4 nibbles are moved 3 nibbles forward. 
( write 0 ... Fh to RAM; start at 40h 

( repeat 16 times: copy index to RAM. 
( with end address and post-decrement: 
( ERROR: overwriting of the source array. 
( write 0 ... Fh to RAM; start at 40h 

( repeat 16 times: copy index to RAM. 
( with end address and post-decrement: 
( 4 nibbles are moved 12 nibbles forward. 



( same result, as with: '4 A16 A16 [12] MOVE' ! 
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4.8.129 NEGATE 



NEGATE 



Purpose: 2's complement of the TOS 4-bit value. 

Category: Arithmetic/logical(single-length)/qFORTH macro 

Library Implementation: CODE NEGATE 

NOT1+ (n»-n) 
END-CODE 
EXP ( n1 -- -n1 ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag not affected 
BRANCH flag set, if (TOS = 0) 
X Y Registers: Not affected 

Bytes Used: 2 
See Also: DNEGATE NOT 



Stack Effect: 
Stack Changes: 
Flags: 
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NEGATE 

Example: 

code true 1 end-code ( this is only a simple example for 'true' ) 

code false 0 end-code 



Negator 
82 - 

2 NEGATE 8 

+ 

= IF true 

ELSE false 
THEN DROP 



(8-2=6 

( 2's complement of 2 add to 8 

( 8 + [- 2 ] = 6 ? 

( is the result equal ? 

( 'true' = 1 = YES ! 

( end of test: drop the result. 
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NOP 



4.8.130 NOP 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



No operation; one instruction cycle of time is used. This 
is useful if the processor has to wait a short time for an 
external device or interrupt. 

Assembler instruction 

7C hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

1 

$AUTOSLEEP 
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NOP 

Example 1 : 

( Library implementation: of SWIO ) 
CODE SWIO 

0 1 SWI NOP 
END-CODE 



( activate the base task ) 
( the NOP gives time for task .. ) 
( switching to the interrupt control logic. ) 



Example 2: 

: Delay ( n -- [wait 4+n*7 cycles, ..] 

#DO ( 1 cycle / ..without S/CALL ] 

NOP NOP NOP ( wait n * 3 cycles 

#LOOP ( wait n * 4 cycles / 1 cycle 

; ( wait 2 cycles 
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NOT 



4.8.131 NOT 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



1's complement of the value on top of the stack. 
Arithmetic/logical(single-length)/assembler instruction 
17 hex 

EXP(n1 ~/n1 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag not affected 

BRANCH flag set, if (/n1 = 0) 

Not affected 

1 

XOR NEGATE OR AND 
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NOP 



Example: 

: NOT_Example 

9 ( --1001b ) 

NOT (9 --0110b ) 

DROP ( 6 -- ) 
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OF 



4.8.132 OF 



Purpose: 



Category: 



Part of the OF ... ENDOF block used within a CASE ... 
ENDCASE control structure. 

OF compares the CASE index value with another 4-bit 
comparison value. If they are equal, both of them are 
dropped from the stack and execution continues with the 
sequence compiled between OF and the next ENDOF. If 
there was no match, only the comparison value is dropped, 
and control proceeds with the word following the next 
ENDOF. 

Control structure/qFORTH macro 



Library Implementation: CODE OF CMP_NE 



(S)BRA _$ENDOF 

DROP 
[E-1R0] 
END-CODE 
EXP ( n1 n2 -- n1 ) 
EXP ( n1 n2 -- ) 
RET ( - ) 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



( n1 n2 - n1 [BRANCH flag] ) 
( if no match then . ) 
( branch to next OF ... ENDOF. ) 
( n1 - ) 



( if no match ) 
( if matched ) 



EXP: 1 element is popped from the stack, if no match 
EXP: 2 elements are popped from the stack, on match 
ET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

3-4 

ENDOF CASE ENDCASE 
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OF 

Example: 



5 CONSTANT Keyboard 
1 CONSTANT TestPortl 
: ONE 1 TestPortl OUT ; 
: TWO 2 TestPortl OUT ; 
: THREE 3 TestPortl OUT ; 
: ERROR DUP TestPortl OUT ; 
( duplicate value for the following 
: CASE-Example 

Key Board IN 

CASE 

1 OF ONE ENDOF 

2 OF TWO ENDOF 

3 OF THREE ENDOF 
ERROR 
ENDCASE 



( write 1 to the TestPortl ' 
(write 2 to the TestPortl' 
( write 3 to the TestPortl ' 
( dump wrong input to the port 
; it drops one n. 

( request 1 -digit keyboard input 
( depending on the input value, 
( one of these words will be 
( activated. 

( otherwise ... 
(n- 
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OR 



4.8.133 OR 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Logical OR of the top two elements on the stack. 
Arithmetic/logical(single-length)/assembler instruction 
OC hex 

EXP ( n1 n2 -- [n1 v n2]) 
RET ( - ) 

EXP: the TOP element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag set, if ([n1 v n2] = 0) 

Not affected 

1 

XOR AND NOT 
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OR 



Example: 



: ERROR 



( what happens in case of errors 



3R@ 3 



#DO 



( show PC, where CPU fails 
( suppress compiler warnings. 



I OUT [ E 0 ] 



#LOOP 



: Logical 



( part of e3400 selftest kernel program ) 



1001b 1100b 

AND 
1000b <> 

IF ERROR THEN ( IF 'result wrong' THEN call 'ERROR' !) 
1010b 0011b 
AND 

0010b <> IF ERROR THEN 
1001b 1100b 
OR 

1 101b <> IF ERROR THEN 
1010b 0011b 
OR 

1011b <> IF ERROR THEN 
1001b 1100b 
XOR 

0101b <> IF ERROR THEN 
1010b 0011b 
XOR 

1001b <> IF ERROR THEN 
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OUT 



4.8.134 OUT 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Write data to one of the 4-bit I/O ports. 
Stack operation/assembler instruction 
1F hex 

EXP (data port-- ) 
RET ( - ) 

EXP: data and address will be popped from the stack 

RET: not affected 

Not affected 

Not affected 

1 

IN 
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OUT 

Example: 

1 CONSTANT Portl 
5 CONSTANT Keyboard 

: Counter 
15 #DO 

I 

Portl OUT 
#LOOP 



INTO 

Keyboard IN ( input HEX value at keyboard - Port 5 ) 

#DO ( DO-LOOP for the 'in' value ) 

Counter ( call and execute the counter routine ) 

#LOOP 



( 15 iterations ) 
( copy the index from the Return Stack) 
( data is output to the port 1 ) 
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OVER 



4.8.135 OVER 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Copies the second element onto the top of stack. 
Stack operation (single-length)/assembler instruction 
27 hex 

EXP ( n2 n1 -- n2 n1 n2) 

RET ( - ) 

EXP: 1 element is pushed onto the top of stack 

RET: not affected 

Not affected 

Not affected 

1 

20VER 
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OVER 

Example: 

: OVER-Example 

3 7 4 (--374 ) 

OVER (374-3747 ) 

2DROP 2DROP (3 747- ) 
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4.8.136 PICK 



PICK 



Purpose: 



Copies a value from anywhere on the EXP stack to the TOS. 
PICK uses the value on the TOS as an index into the stack, 
and copies the value from that location in the stack. The 
value on the TOS [not including the index] is the Oth element. 

0 <= x <= 14 

Note: The actual EXP stack depth is not checked by this function, 
therefore the user should use the DEPTH instruction to 
ensure that the defined PICK index value is valid. ( i.e., 
that the depth of the stack permits the desired index) 

Category: Stack operation (single-length)/qFORTH colon definition 

Library Implementation: : PICK SP@ ROT 1+ M- ( x SPh SPI -- SPh' SPI' ) 

Y![Y-]@ ( SPh' SPI 1 -- n[x] ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( x -- n[x] ) 
RET ( - ) 
EXP: not affected 
RET: not affected 

CARRY and BRANCH flags are affected 
The contents of the Y register will be changed 
8 + 'M-' 
ROLL 
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Example: 



PICKl 



( 0 PICK is equivalent to DUP ) 
( 1 PICK is equivalent to OVER ) 
: PickRoll 
12345678 

9 Ah Bh Ch Dh Eh Fh 0 1 2 3 4 



0 PICK DROP 


( ..2 34- 


..2 34 4 


1 PICK DROP 


( ..2 34- 


..2 34 3 


2 PICK DROP 


( ..2 34- 


..2 34 2 


9 PICK DROP 


( ..2 34- 


..2 34 B 


14 PICK DROP 


( ..2 34- 


..2 34 6 


( *** ROLL *** 






0 ROLL 


( ..2 34- 


..2 3 4 


1 ROLL 


( ..2 34- 


..2 4 3 


13 ROLL 


( ..24 3- 


..2437 



10 #DO DROP #LOOP 
10 #DO DROP #LOOP 



write data onto the stack: 
20 values. 



( clear the stack: 20 DROPs ) 
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R> 



4.8.137 R-from 



Purpose: 



Removes the top 4-bit value from the Return Stack and puts 
the value on the Expression Stack. 

R> pops the RET stack onto the EXP stack. To avoid 
corrupting the RET stack and crashing the system, each use 
of R> MUST be preceded by a >R within the same colon 
definition. 



Category: 



Stack operation (single-length)/qFORTH macro 
Library Implementation: CODE R> 

R@ DROPR (copy the index and drop the RET stack) 
END-CODE 
EXP ( -- n ) 
RET(u| u| n~) 

EXP: 1 element is pushed onto the stack 
RET: 1 element (3 nibbles) is popped from the stack 
Not affected 
Not affected 
2 

>R I 2>R 2R@ 2R> 3>R 3R@ 3R> 



Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers 
Bytes Used: 
See Also: 
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R> 

Example: 



: 2SWAP ( swap 2nd byte with top ) 

>R <ROT ( d1 d2 -- n2_h d1 ) 

R> <ROT ( n2_h d1 -- d2 d1 ) 

: M/MOD ( d n -- n_quot n_rem ) 

>R Fh <ROT ( save divider on RET ) 

BEGIN ( preset quotient = -1 ) 

ROT 1+ <ROT ( increment quotient ) 

R@ M- ( subtract divider ) 

UNTIL ( until an underflow occurs ) 



D>S R> + ( n_quot d_rem-n - n_quot n_rem ) 
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4.8.138 R-depth 



RDEPTH 



Purpose: 
Category: 

Library Implementation: 



Leaves the depth of the RET stack, the current number of 
12-bit entries, on top of the EXP stack. 

Interrupt handling/qFORTH colon definition 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



RDEPTH RP@ 
D2/ D2/ 
NIP 



( -- RPh RPI ) 
(compute the modulo 4 number ) 
(of entries on the RET stack ) 
(forget entry of RDEPTH itself ) 



EXP ( -- n ) 
RET ( - ) 

EXP: 1 element is pushed onto the stack. 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

12 

DEPTH RFREE INTO ... INT7 
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RDEPTH 

Example: 

: Call_Again2 

RDEPTH ( result is 2. ) 



: Call_Again1 

RDEPTH (result is 1. ) 

Call_Again2 ( next level - new address to RET. ) 



( result is 0. ) 
( next level - new address to RET. ) 
( all results into wpb [waste]. ) 

: $RESET 
>RP NoRAM 
>SP SO 

RDepth_Example 



: RDepth_Example 
RDEPTH 
Call_Again1 
3DROP 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-299 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



REPEAT 



4.8.139 REPEAT 



Purpose: 
Category: 

Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Part of the BEGIN ... WHILE ... REPEAT control structure. 

REPEAT forces an unconditional branch back to just after the 
corresponding BEGIN statement. 

Control structure/qFORTH macro 

CODE REPEAT 

SET_BCF ( set BRANCH flag, force jump ) 

BRA _$BEGIN ( jump back to BEGIN ) 
_$LOOP: [ E 0 R 0 ] 

END-CODE 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY and BRANCH flags are set 

Not affected 

2-3 

BEGIN WHILE UNTIL AGAIN 
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REPEAT 

Example: 

1 CONSTANT Portl 
VARIABLE Count 
: COUNTER 

Count 1+! ( increment Count ) 

Count @ Portl OUT ( write new Count to Portl ) 

: BEGIN-WHILE-REPEAT 

10 BEGIN 1- ( decrement the TOS from 10 to 0 ) 

DUP ( save TOS ) 

0<> WHILE ( REPEAT decrement while TOS not equal 0 ) 

COUNTER ( other instructions in this loop ... ) 

REPEAT ( after each decrement the TOS contains ) 

; ( the value of the present index. ) 
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RFREE 

4.8.140 R-free Purpose: Leaves the number of currently unused Return Stack entries 

on top of the Expression Stack, e.g. the available levels of 
nesting. 

Moves the addresses of the Return Stack Pointer and the 
Expression Stack base address [SO] onto the Expression 
Stack and subtracts them. 

Final result = number of free levels for further 'calls'. 
Category: Interrupt handling/qFORTH macro 

Library Implementation: : RFREE RDEPTH SO ( Rn -- Rn SOh SOI ) 

D2/D2/NIP ( Rn SOh SOI -- Rn Sn ) 

SWAP - ( Rn Sn -- Rfree ) 

I 

EXP ( -- n ) 
RET ( - ) 

EXP: one nibble is pushed onto the Expression Stack 
RET: not affected 

CARRY and BRANCH flags are affected 
Not affected 
17 + 'RDEPTH' 
DEPTH RDEPTH 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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Example: 



RFREE 



VARIABLE RO 27 ALLOT 



VARIABLE SO 19 ALLOT 



( return stack: 28 nibbles, used 21 for ) 

( 7 levels of task switching - additionally : ) 

( 7 nibbles are free for 1 -nibble-variables. ) 

( data stack: 20 nibbles. ) 



RFree3 
RFREE DROP 



( result value is: 4 



RFree2 
RFREE DROP 
RFree3 



( result value is: 5 
( "call" next level. 



RFreel 

RFREE DROP 
RFree2 



( result value is: 6 
( "call" next level. 



: INTO 
RFREE DROP 
RFreel 



( result value is: 7 
( "call" next level. 
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4.8.141 Rotate-left 



ROL 



Purpose: 



Rotate the TOS left through CARRY. 
TOS 



c 




3 


2 


1 


0 


<— 


+ 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Arithmetic/logical(single-length)/assembler instruction 

11 hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag = Bit3 of TOS - before operation 
BRANCH flag = CARRY flag 
Not affected 
1 

ROR SHR SHL D2* 
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ROL 



Example: 

: BitShift 



SET_BCF 3 


(3 = 0011b ; 


ROR DROP 


( [CARRY] 3 -- [CARRY] 9 = 1 001 b ) 


CLR_BCF 3 


(3 = oonb ; 


ROR DROP 


( [no CARRY] 3 -- [CARRY] 1 = 0001 b ; 


SET_BCF 3 


(3 = ooiib ; 


ROL DROP 


( [CARRY] 3 - [no CARRY] 7 = 01 1 1 b ) 

\L J L J 


CLR_BCF 3 


(3 = 0011b ; 


ROL DROP 


( [no CARRY] 3 -- [no CARRY] 6 = 01 1 0b ; 


CLR_BCF Fh 




21 DROP 


( - SHR - [no CARRY] F -- [CARRY] 7 = 01 1 1 b 


CLR_BCF 6 


(6 = 01 10b ; 


2* DROP 


( - SHL - [no CARRY] 6 -- [no C] C = 1 1 00b 
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4.8.142 Rol-L 



ROLL 



Purpose: 



Category: 

Library Implementation: 
IF 

CCR@ Dl >R 
1+ PICK>R 



1 M+X! 

#DO [+X]@ [+Y]! #LOOP 
DROP R> 
R> CCR! 
ELSE DROP THEN 



MOVES a value from anywhere on the EXP stack to the 
TOS. ROLL uses the value on the TOS as an index into the 
stack and moves the value at that location onto the TOS. The 
value on the TOS [not including the index] is the Oth element. 

0 <= x <= 13 

'0 ROLL, does nothing, 

'1 ROLL, is the same as SWAP, and 

'2 ROLL, is equivalent to ROT. 

'3 ROLL, ie. corresponds to ( n1 n2 n3 n4 -- n2 n3 n4 n1 ) 
Stack operation (single-length)/qFORTH colon definition 
: ROLL ?DUP 



( save current l-flag setting on RET 
( move PICKed value on RET 
( move ptr from Y -> X reg. 
( adjust X reg. pointer 
(shift data values one down 



( restore l-flag setting in CCR 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP (x--) 
RET ( - ) 

EXP: 1 element is popped from the stack 
RET: not affected 

CARRY and BRANCH flags are affected 

Both the X and Y index registers will be affected 

39 + 'PICK' + 'M+' 

PICK 
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Example: 



ROLL 



PickRoll 
12345678 

9 Ah Bh Ch Dh Eh Fh 0 1 2 3 4 

0 PICK DROP 

1 PICK DROP 

2 PICK DROP 

9 PICK DROP 
14 PICK DROP 

0 ROLL 

1 ROLL 
13 ROLL 

10 #DO DROP DROP #LOOP 



write data onto the stack: 
20 values. 

..2 34-..2 34 4=DUP 

..2 34-..2 343=OVER 

..2 34 --..2 34 2 

. .2 34 --..2 34 B 

..2 34 --..2 346 

..2 34 --..2 34 = NOP 

..2 3 4 -- ..2 4 3 = SWAP 

..243-- ..2437 

clear the stack with 20*DROP 
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ROM Byte ©TABLE 



4.8.143 ROM-byte-fetch 



Purpose: 

Category: 
MARC4 Opcode: 
Library Implementation: 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Fetches an 8-bit constant from ROM onto TOS, whereby the 
12-bit ROM address is on the Expression Stack. 

Memory operation (double-length)/qFORTH colon definition 

20 hex (TABLE) 

: ROMByte® ( ROMh ROMm ROMI ~ d 

3>R ( move TABLE address to RET stack 

TABLE ( -- consthigh constlow 

(TABLE returns directly to the CALLer 
during the microcode execution 

[ E -1 R 0 ] ;; ( therefore 'EXIT is not required 

EXP ( ROMh ROMm ROMI -- consth constl 

RET ( - ) 

EXP: 1 element will be popped from the stack 
RET: not affected 
Not affected 
Not affected 
2 

DTABLE® ROMCONST 
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ROM Byte @ TABLE 



Example: 

ROMCONST DigitTable 10h , 1 , 2 , 3 , 4 , 45h , 6 , 7, 8 , 9, Ah , Bh , Ch , Dh , Eh , OFh 
( Pay attention to the blanks before and after the ',' and to the last ',' ) 



D_Table@ 
0 0 1 ROMByte® 
2DROP 
DigitTable 3>R 

3R@ 5 

DTABLE® 2DROP 
3R@ 1 

DTABLE® 2DROP 
3R@ 

ROMByte® 2DROP 

DigitTable 15 
DTABLE® 2DROP 



fetch byte at address 001 h : OFh = SLEEP 
delete it. 

save address of L/U table on RET stack 

sixth byte of the table: 

put address and index on the stack. 

fetch and delete the value : 45h . 

second byte of the table: 

put address and index on the stack. 

fetch and delete the value : 01 h . 

first byte of the table and min. index : 

put address on the stack. 

fetch and delete the value : 1 0h . 

last byte of the table and max. index 

put address and index on the stack. 

fetch and delete the value : OFh 
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ROMCONST 



4.8.144 ROM-CONSTANT Purpose: 



Category: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Defines 8-bit constants in the ROM for look-up tables or 
as ASCII string constants. 

Pay Attention to the blanks before and after the ',' and to 
the last ' , ' 

Predefined data structure 
EXP (-) 
RET (-) 
EXP: not affected 
RET: not affected 
Not affected 
Not affected 

Depends on number of defined table items (bytes) 
DTABLE® ROMByte® 



Please note, that only a macro, colon or VARIABLE definition is allowed following a 
table definition 

ROMCONST Tab1 10h, 13h, 55, 

23h 2CONSTANT #Apples 

is not allowed since a ',' is exspected after 23h. 
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ROMCONST 

Example 1 : 

13 CONSTANT TextLength 03h CONSTANT LCD_Data 
ROMCONST LCD_Text TextLength , " MARC4 Test " 



: ExampleText 

TextLength #DO ( loop TextLength' times. 

LCD_Text I DTABLE® ( gets: 2Eh 44h 'D',..54hT 

DecodeAscii ( convert 8-bit -> 1 6-bit - segm. 

4 #DO LCD_Data OUT ( write 4 * 4-bit to LCD. 

[ E 0 ] #LOOP ( suppress warnings of compiler. 
[ E 0 ] #LOOP 



Example 2: 



0 CONSTANT Aa 

1 CONSTANT Ab 

2 CONSTANT Ac 

3 CONSTANT Ad 
ROMCONST Matrix 



0 CONSTANT P1 

1 CONSTANT P2 

2 CONSTANT P3 

3 CONSTANT P4 

11 , 12 , 13 , 14 
21 , 22 , 23 , 24 
31 , 32 , 33 , 34 
41 , 42 , 43 , 44 



: L/U-Table 
2>R 
Matrix 

R@ 2* S>D D2* 
D+ 

IF ROT1+<ROT THEN 
2R> DROP 
DTABLE® ; 
: Exam2 Ab P4 L/U-table 



( Ss Pn -- 8-bit-value 
( save indices on Return Stack 
( push matrix base address 
( compute parameter set offset 
( ROMaddr := matrix + Pn * 4 
( handle MSD of matrix address 
( load Aa ... Ad from RET stack 
( fetch indexed value from ROM 
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4.8.145 Rotate-right 



ROR 



Purpose: 



Rotate right through CARRY 



-• C 



TOS 



— > 



3 


2 


1 


0 



— > 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Arithmetic/logical (single-length)/assembler instruction 

13 hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag = bitO of TOS - before operation 
BRANCH flag = CARRY flag 
Not affected 
1 

ROLSHRSHL 
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Example: 



RORl 



BitShift 
SET_BCF 3 
ROR DROP 
CLR_BCF 3 
ROR DROP 
SET_BCF 3 
ROL DROP 
CLR_BCF 3 
ROL DROP 



(- 



CLR_BCF Fh 
21 DROP 

CLR_BCF 6 
2* DROP 



(3 = 0011b 

( [CARRY] 3 -- [CARRY] 9 = 1 001 b 
(3 = 0011b 

( [no CARRY] 3 -- [CARRY] 1 = 0001b 
(3 = 0011b 

( [CARRY] 3 -- [no CARRY] 7 = 01 1 1 b 
(3 = 0011b 

( [no CARRY] 3 -- [no CARRY] 6 = 01 1 0b 



( 

( - SHR - [no CARRY] F -- [CARRY] 7 = 01 1 1 b 

( 

(6 = 01 10b 

( - SHL - [no CARRY] 6 -- [no C] C = 1 1 00b 
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[ROT 



4.8.146 Rote 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Moves the third value on the stack to the top of the stack. 
Stack operation (single-length)/assembler instruction 
2C hex 

EXP ( n1 n2 n3 -- n2 n3 n1 ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

Not affected 

Not affected 

1 

2 ROT <ROT 2<ROT 
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ROT 

Example: 

: ROTATE_Example 
4 6 9 (--469 ) 

ROT (469-694 ) 

3DROP (694- ) 
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4.8.147 R-P-fetch 



RP 



Purpose: 
Category: 
MARC4 Opcodes: 
Stack Effect: 



Stack Changes: 



Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Fetch the Return Stack pointer. 
Assembler instruction 
71 hex 

EXP ( -- RPh RPI ) 
RET ( - ) 

EXP: 2 elements are pushed onto the stack 

RET: not affected 

RET: new base address 

Not affected 

Not affected 

1 

SP! SP@ >SP $xx RP! >RP FCh RO 
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RP@ 

Example: 

VARIABLE RO 47 ALLOT ( Return Stack: 48 nibbles 1 3 entry levels ) 

VARIABLE SO 1 9 ALLOT ( Data Stack: 20 nibbles. ) 



( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack 
( pointer onto the Expression Stack 



: RDEPTH ( implementation code 

RP@ (EXP stack: -- RPh RPI 

D2/ D2/ ( compute number of entries on the RET stack 

NIP ( EXP stack : 0 n -- n 

1 - ( forget the entry of RDEPTH itself. 



$RESET 

> SP SO ( initialize the stack pointers. ) 

> RP FCh ( set RP to autosleep address. ) 
RDEPTH DROP ( result is 0 ) 
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RP! 



4.8.148 R-P-store 



Purpose: 
Category: 
MARC4 Opcodes: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Restore the Return Stack pointer. 
Assembler instruction 
75 hex 

RP!: EXP ( RPh RPI -- ) 
RET ( - ) 

RP! EXP: 2 elements are popped from the stack 

RET: Return Stack pointer modified 

Not affected 

Not affected 

1 

SP! SP@ >SP $xx RP@ >RP FCh RO 
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RP! 

Example: 

VARIABLE RO 47 ALLOT ( Return Stack: 48 nibbles 1 3 entry levels ) 

VARIABLE SO 1 9 ALLOT ( Data Stack: 20 nibbles. ) 



( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack 
( pointer onto the Expression Stack 



: RDEPTH ( implementation code 

RP@ ( EXP stack :-- RPh RPI 

D2/ D2/ ( compute number of entries on the RET stack 

NIP ( EXP stack : 0 n -- n 

1 - ( forget the entry of RDEPTH itself. 



$RESET 

> SP SO ( initialize the stack pointers. ) 

> RP FCh ( set RP to autosleep address. ) 
RDEPTH DROP ( result is 0 ) 
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>RP FCh, RO 



4.8.149 To-RP Address 



Purpose: 
Category: 
MARC4 Opcodes: 

Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Initialization of the Return Stack pointer. 

Assembler instruction 

RO: predefined data structure 

>RP $xx = 79xx hex 

>RP $xx: EXP ( -- ) 

RET(-) RP:=$xx 

>RP $xx EXP: not affected 

RET: new base address 

Not affected 

Not affected 

2 

SP!SP@ >SP$xx RP@ RP! 
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>RP FCh, RO 

Example: 

VARIABLE RO 47 ALLOT ( Return Stack: 48 nibbles 1 3 entry levels ) 

VARIABLE SO 1 9 ALLOT ( Data Stack: 20 nibbles. ) 



( the qFORTH word RDEPTH uses 'RP@' to push the Return Stack 
( pointer onto the Expression Stack 



: RDEPTH ( implementation code 

RP@ ( EXP stack :-- RPh RPI 

D2/ D2/ ( compute number of entries on the RET stack 

NIP ( EXP stack : 0 n -- n 

1 - ( forget the entry of RDEPTH itself. 



$RESET 

> SP SO ( initialize the stack pointers. ) 

> RP FCh ( set RP to autosleep address. ) 
RDEPTH DROP ( result is 0 ) 
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q FORTH Language Dictionary 



S>D 



4.8.150 Single-to-double Purpose: 



Transform a 4-bit value to an unsigned 8-bit value. Pushes 0 
onto the 2nd stack position. 



Category: Stack operation/qFORTH macro 

Library Implementation: CODE S>D LIT_0 ( n - n 0 ) 

SWAP ( n 0 - d ) 

END-CODE 
EXP ( n -- d ) 
RET ( - ) 

EXP: 1 element (0) is pushed onto the 2nd stack position 
RET: not affected 
Not affected 
Not affected 
2 

D>S 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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q FORTH Language Dictionary 



S>D 



Example: 

: Bytes & Nibbles 



4 ( - 4 

S>D ( 4 -- 0 4 

25h D+ (0 4 2 5 - 2 9 

D>S ( 2 9 -- 9 

DROP ( 9 -- 
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q FORTH Language Dictionary 



SP@ 



4.8.151 S-P-fetch 



Purpose: 
Category: 
MARC4 Opcodes: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Fetch the Expression Stack pointer onto the TOS. 
Assembler instruction 
70 hex 

EXP ( -- SPh SPI ) 
RET ( - ) 

EXP: 'stack pointer + 1 ' is pushed onto the stack 

RET: not affected 

Not affected 

Not affected 

1 

RP! RP@ >RP FCh SP! >SP SO 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-324 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



SP@ 



Example 1 : 

VARIABLE SO 34 ALLOT \ Define EXP stack depth 
VARIABLE RO 80 ALLOT \ Define 21 RET stack entries 

( The qFORTH word DEPTH uses 'SP@' to push the EXP stack ) 
( pointer onto the Expression Stack ) 

: DEPTH SP@ ( -- SPh SPI ) 

SO ( SPh SPI -- SPh SPI SOh SOI ) 

D- ( SPh SPI SOh SOI -- diffh diffl ) 

NIP ( 0 n -- n ) ( result only on nibble, max Fh ) 

1 - ( the value of SP on stack is incremented. ) 

: $RESET 

> SP SO ( initialize the stack pointers. ) 

> RP NoRAM ( Set RP to autosleep address. ) 
DEPTH DROP (result is 0 ) 

> 

Example 2: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 
: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 

[X]@ 0+C[X]! 

: SRAMINIT ( - - ) 



>SP F9h 



SP@ X! 



0 



begin 



DROP 



Fh [X]! [X-]@ NOT 
Oh [X]! [X-]@ OR 
TOG_BF 7LEAVE DROP 



X@ 1-OR 
until 



( Test all addresses except 00 & 01 
( Attention: RETURN address stack! 



Error_Flag ! 
>SP SO 
[EON]; 



( Save result in Error_Flag at FFh 
( Reset STACKPOINTER again !! 
( Don't place in 'ZERO PAGE' 
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q FORTH Language Dictionary 



SLEEP 



4.8.152 Sleep 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The SLEEP instruction forces the MARC4 CPU into sleep 
mode, whereby the internal CPU clock is halted. 

The internal RAM data keeps valid during sleep mode. To 
wake up the CPU again, an interrupt must be received from a 
module (timer/counter, external interrupt pin or other 
modules). The CPU starts running at the ROM address 
where the interrupt service routine is placed. 

Note: It is not recommended to use the SLEEP instruction other 
than in the $RESET level or the $AUTOSLEEP routine 
because it might result in unwanted side effects within 
other interrupt routines. If any interrupt is active or pending, 
the SLEEP instruction will be executed in the same way as 
an NOP 

Interrupt handling/assembler instruction 

OF hex 

EXP ( - - ) 

RET ( - - ) 

EXP: not affected 

RET: not affected 

LENABLE flag: set 

CARRY and BRANCH flags: not affected 

Not affected 

1 

Dl, El, RTI, $AUTOSLEEP 
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q FORTH Language Dictionary 



SLEEP 

Example: 

\ After POR, wait in power-down mode until a key is pressed to start the application 

: System Jnit 

Setup_Peripherals 

Enable_Keylnt 

SLEEP 

NOP NOP 
BEGIN Port5 IN 

Port5 IN AND Fh = 

UNTIL 

Choose_Display \ Show power-up display 

1_Hz .Set_BaseTimer \ Setup 1 Hz INT5 



\ Enable INT1 for nest key input 
\ Wait for INT1 to happen here 
\Allow INT processing 
\ Wait until no key is pressed 
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q FORTH Language Dictionary 



SP! 



4.8.153 S-P-store 



Purpose: 
Category: 
MARC4 Opcodes: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Restore the Expression Stack pointer. 
Assembler instruction 
74 hex 

EXP ( SPh SPI -- ) 
RET ( - ) 

EXP: 2 elements are popped into the stack pointer 

RET: not affected 

Not affected 

Not affected 

1 

RP! RP@ >RP $xx SP@ >SP SO 
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q FORTH Language Dictionary 



SP! 

Example: 

VARIABLE SO 34 ALLOT 
VARIABLE RO 80 ALLOT 



\ Define EXP stack depth 
\ Define 21 RET stack entries 



SP_ex DUP 0<> (n - - n) 

IF 2Ah \ This is a stupid example to re-adjust SP 

ELSE 2Fh 
THEN SP! 
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q FORTH Language Dictionary 



>SP so 



4.8.154 To-SPS-zero 



Purpose: 
Category: 
MARC4 Opcodes: 

Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Initialization of the Expression Stack pointer. 

Assembler instruction 

SO: predefined data structure 

>SP $xx = 78xx 

EXP ( - ) 

RET ( - ) 

EXP: the Expression Stack pointer is initialized 

RET: not affected 

Not affected 

Not affected 

2 

RP! RP@ >RP$xxSP@ SP! 
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q FORTH Language Dictionary 



>SP so 

Example 1 : 

VARIABLE SO 34 ALLOT \ Define EXP stack depth 
VARIABLE RO 80 ALLOT \ Define 21 RET stack entries 



( The qFORTH word DEPTH uses 'SP@' to push the EXP stack 
( pointer onto the Expression Stack 



: DEPTH SP@ ( -- SPh SPI 

SO ( SPh SPI -- SPh SPI SOh SOI 

D- ( SPh SPI SOh SOI -- diffh diffl 

NIP ( 0 n -- n ) ( result only on nibble, max Fh 

1 - ( the value of SP on stack is incremented. 



$RESET 
>SPS0 
> RP NoRAM 
DEPTH DROP 



( initialize the stack pointers. 
( Set RP to autosleep address. 
( result is 0 



Example 2: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 
: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 

[X]@ 0+C [X]! 



SRAMINIT 
>SP F9h 
SP@ X! 



(--) 



0 

begin 



DROP 

Fh [X]! [X-]@ NOT 
Oh [X]! [X-]@ OR 
TOG_BF 7LEAVE DROP 
X@ 1-OR 



until 

Error_Flag ! 

>SP SO 
[EON]; 



( Test all addresses except 00 & 01 
( Attention: RETURN address stack! 
( Save result in Error_Flag at FFh 

( Reset STACKPOINTER again !! 
( Don't place in 'ZERO PAGE' 
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q FORTH Language Dictionary 



SET BCF 



4.8.155 Set-BRANCH-and 
-CARRY-flag 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Set the state of the BRANCH and CARRY flag in the MARC4 
condition code register. 

Assembler instruction 

19 hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag set 

BRANCH flag set 

Not affected 

1 

TOG_BCF CLR_BCF 
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q FORTH Language Dictionary 



Example: 



SET BCF 



Error 
3R@ 3 
#D 

I OUT [ E 0 ] 
#LOOP 



( what happens in case of error: 



) 



( show PC, where CPU fails ) 
( suppress compiler warnings ) 



CCRf CCR@ 1010b AND 



( fetch - mask the used flags out 



BC_Flags 
SET_BCF 
CCRf 1010b 
<> IF Error THEN 
CLR_BCF 
CCRf 0000b 
<> IF Error THEN 
CLR_BCF 
TOG_BF 
CCRf 0010b 
<> IF Error THEN 
SET_BCF 
TOG_BF 
CCRf 1000b 
<> IF Error THEN 



flags: C%BI - CARRY % BRANCH x 
BRANCH and CARRY flag is set 
no error occured 

delete BRANCH and CARRY flag 
all flags reset or masked off 
no error occured 

clear table from the compare before 

0000 -> 00B0 

BRANCH flag is set 

no error occured 

define new machine state 

C%B% -> C%0% 

CARRY flag is still set 

no error occured 
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q FORTH Language Dictionary 



SWAP 



4.8.156 SWAP 



Purpose: 
Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Exchange the top two elements on the Expression Stack. 
Stack operation (single-length) 
26 hex 

EXP ( n2 n1 -- n1 n2 ) 
RET ( - ) 

EXP: exchanges the top two elements with one another 

RET: not affected 

Not affected 

Not affected 

1 

2SWAP OVER 
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q FORTH Language Dictionary 



SWAP 

Example: 



: SWAP-Example 



374 


( 




3 


7 4 


) 


SWAP 


( 


3 


7 


4 -- 3 4 


7 ) 


DROP 


( 


3 


4 


7 -- 3 4 


) 


+ 0= 


( 


3 


4 


7 


) 
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q FORTH Language Dictionary 



SWIO ... SWI7' 



4.8.157 Software-interrupt 
-zero ... Software 
-interrupt-seven 



Purpose: These qFORTH words generate a software interrupt. They 

allow the programmer to postpone less important tasks until 
all the important work is completed. Under special 
circumstances, it may also be used to spawn higher priority 
jobs from a lower priority task to make them less 
interruptable. 

Category: Interrupt handling 

Library Implementation: CODE SWI3 0 8 SWI NOP (NOP gives time for task switch ) 

END-CODE 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
Not affected 
Not affected 
4 

RTI INTO ... INT7 
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q FORTH Language Dictionary 



'SWIO ... SW17' 



Example: 

: INT3 ( software triggered interrupt #3 ) 

UpdateLCD ( update LCD display ) 

> 

: INT5 ( external hardware interrupt - level 5 ) 

ScanKeys ( do most important action here and now ) 

SWI3 ( more action later, after this job is ) 

Count 1+! ( finished; activated from the interrupt ) 

Count @ 0= ( logic after the higher prioritised ) 

IF Overflow THEN ( job is completed. ) 

; ( compiler translates ';' to 'RTT. ) 
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T+! 



4.8.158 T-plus-store 



Purpose: 



Category: 



ADD the TOS 12-bit value to a 12-bit variable in RAM and 
store the result in that variable. On function entry, the 
start/base address of the array is the TOS value. 

Memory operation (triple-length)/qFORTH colon definition 



Library Implementation: : T+! 2 M+ 

Y! 

[Y]@ + 
[Y-]! 

[Y]@ +c 
[Y-]! 

[Y]@ +c 
[Y]l 



( increment addr 

( nh nm nl addr - nh nm nl 

( nh nm nl - nh nm nl' 

( nh nm nl' -- nh nm 

( nh nm - nh nm' 

( nh nm' -- nh 

( nh -- nh' 

( nh' -- 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( nh nm nl addr - ) 
RET ( - ) 

EXP: 5 elements are pushed from the stack 
RET: not affected 

CARRY flag set if arithmetic overflow 

BRANCH flag = CARRY flag 

The contents of the Y register will be changed 

14 + 'M+' 

3@ 3! T-! 
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q FORTH Language Dictionary 



Example: 



3 ARRAY 3Nibbles AT 40h 



T+! 



Triples 

123h 3Nibbles3! 
321 3Nibbles T+! 
3Nibbles 3@ 3>R 
123h 3Nibbles T-! 
DROPR 



( store 123 in the 3 nibbles array. 
( 123 + 321 =444 
( save the result onto Return Stack. 
( 444 - 123 = 321 

( forget the saved result on Return Stack. 
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q FORTH Language Dictionary 



T-! 



4.8.159 T-minus-store 



Purpose: 



Category: 



Subtracts the TOS 12-bit value from a 12-bit variable in RAM 
and stores the result in that variable. On function entry the 
start/base address of the array is the TOS value. 

Memory operation (triple-length)/qFORTH colon definition 



Library Implementation: : T-! 



2 M+ 
Y! 

[Y]@ SWAP 
- [Y-]! 
[Y]@ SWAP 
-c [Y-]! 
[Y]@ SWAP 
-c [Y]! 



( increment addr 
( nh nm nl addr - nh nm n 
( nh nm nl - nh nm rl nl 
( nh nm rl nl -- nh nm 
( nh nm - nh rm nm 
( nh rm nm -- nh 
( nh -- rh nh 
( rh nh - 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( nh nm nl addr - ) 
RET ( - ) 

EXP: 5 elements are pushed from the stack 
RET: not affected 

CARRY flag set, if arithmetic underflow 

BRANCH flag = CARRY flag 

The contents of the Y register are changed 

17 + 'M+' 

3@ 3! T+! 
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q FORTH Language Dictionary 



Example: 



3 ARRAY 3Nibbles AT 40h 



T-! 



Triples 

123h 3Nibbles3! 
321 3Nibbles T+! 
3Nibbles 3@ 3>R 
123h 3Nibbles T-! 
DROPR 



( store 123 in the 3 nibbles array. 
( 123 + 321 =444 
( save the result onto Return Stack. 
(444- 123 = 321 

( forget the saved result on Return Stack 
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TD+! 



4.8.160 T-D-plus-store 



Purpose: 
Category: 

Library Implementation: 



ADD the 8-bit number on the stack to a 12-bit element in 
RAM and store the result in that variable. On function entry, 
the start base address of the array is the TOS value. 

Arithmetic/logical (triple-length)/qFORTH colon definition 

: TD+! 



2 M+ 


( increment addr 


Y! 


( nh nl addr -- nh nl 


[Y]@ + 


( nh nl -- nh rl' 


[Y-]! 


( nh rl' - nh 


[Y]@ +c 


( nh - nh rm' 


[Y-]! 0 


( nh rm' - 0 


[Y]@ +c 


( 0 - rh' 


[Y]l 


( rh' - 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 



EXP (daddr- ) 
RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 

CARRY flag set if arithmetic overflow 
BRANCH flag = CARRY flag 
The contents of the Y register are changed 
15 + 'M+' 
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q FORTH Language Dictionary 



TD+! 

Example: 

3 ARRAY 3Nibbles 
: TripDigi 

F87h 3Nibbles 3! ( store F87 in the RAM. ) 

44h 3Nibbles TD+! ( F87 + 44 = FCB CARRY: % BRANCH: % ) 

44h 3Nibbles TD+! ( FCB + 44 = [1]00F CARRY: 1 BRANCH: 1 ) 

44h 3Nibbles TD-! ( OOF - 44 = FCB CARRY: 1 BRANCH: 1 ) 

44h 3Nibbles TD-! ( FCB - 44 = F87 CARRY: % BRANCH: % ) 
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TD-! 



4.8.161 T-D-minus-store 



Purpose: 



Category: 

Library Implementation: 



SUBTRACT the 8-bit number on the stack from an 12-bit 
element in RAM and store the result in that variable. On 
function entry, the start base address of the array is the TOS 
value. 

Arithmetic/logical (triple-length)/qFORTH colon definition 
: TD-! 



2 


M+ 


( increment addr 


Y! 




( nh nl addr - nh nl 


[Y]@ 


SWAP 


( nh nl - nh rl nl 




[Y-]! 


( nh rl nl -- nh 


[Y]@ 


SWAP 


( nh -- rm nh 


-c 


[Y-]! 


( rm nh - [borrow] 


[Y]@ 


0 


( [borrow] - rh 0 


-c 


[Y]l 


( rh 0 - 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



EXP ( d addr - ) 
RET ( - ) 

EXP: 4 elements are popped from the stack 
RET: not affected 

CARRY flag set if arithmetic underflow 

BRANCH flag = CARRY flag 

The contents of the Y register are changed 

17 + 'M+' 

3@ 3! T-! 
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q FORTH Language Dictionary 



TD-! 

Example: 



3 ARRAY 3Nibbles 



TripDigi 

F87h 3Nibbles 3! 
44h 3Nibbles TD+! 
44h 3Nibbles TD+! 
44h 3Nibbles TD-! 
44h 3Nibbles TD-! 



( store F87 in the RAM. 
( F87 + 44 = FCB CARRY: % BRANCH: % 
( FCB + 44 = [1]00F CARRY: 1 BRANCH: 1 
( OOF - 44 = FCB CARRY: 1 BRANCH: 1 
( FCB - 44 = F87 CARRY: % BRANCH: % 
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q FORTH Language Dictionary 



THEN 



4.8.162 THEN 



Purpose: 



Category: 



Part of the IF ... ELSE ... THEN control structure which closes 
the corresponding IF statement. 

The IF block will be executed ONLY if the condition is TRUE, 
otherwise - if available - the ELSE block is executed. If the 
condition is FALSE, the processing goes on with the ELSE 
part; if there is no ELSE part, the processing goes on after 
the THEN label. 

Control structure 



Library Implementation: CODE THEN 

_$THEN: [ E 0 RO] 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 

CARRY and BRANCH flags are affected 

Not affected 

0 

IF ELSE 
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q FORTH Language Dictionary 



Example: 



THEN 



IfElseThen 
1 2 <= 
IF 

1 

ELSE 
0 

THEN 

1 2 > 
IF 

DROPO 
THEN 

1 2 > 
IF 

0 

ELSE 
1 

THEN 2DROP 



is 1 <= 2 ? 

yes, so the If block is executed, 
a 1 will be pushed onto the stack. 

true => no execution of the ELSE block. 

is 1 > 2 ? 

false: nothing will be executed. 



is 1 > 2 ? 

not true => no execution. 

in this case, the 

ELSE block will be executed 

the results from the expression stack. 
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q FORTH Language Dictionary 



TOGGLE 



4.8.163 TOGGLE 



Purpose: 



TOGGLES [exclusive-or] a 4-bit variable at a specified 
memory location with a given bit pattern. On entry to this 
function, the 8-bit address of the variable is on the top of 
stack. 



Category: Memory operation (single-length)/qFORTH macro 

Library Implementation: CODE TOGGLE 

Y! (n1addr~n1 ) 

[Y]@ ( n1 -- n1 n2 ) 

XOR ( n1 n2 -- n3 ) 

[Y]l ( n3 - ) 

END-CODE 
EXP(n1 addr-) 
RET ( - ) 

EXP: 3 elements are popped from the stack 
RET: not affected 
CARRY flag not affected 
BRANCH flag Set, if (TOS = 0) 
The contents of the Y or X register may be changed 
4 

DTOGGLE XOR 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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q FORTH Language Dictionary 



TOGGLE 

Example: 



VARIABLE Hoss 
: D_Toggle 

5 Hoss ! ( set in the RAM one nibble to 01 01 

3 Hoss TOGGLE ( truth table: 01 01 XOR 001 1 = 01 1 0 

( flags: no BRANCH 
Fh Hoss ! ( set in the RAM one nibble to Fh. 

Fh Hoss TOGGLE ( 1 1 1 1 XOR 1 1 1 1 = 0000 

( flags: BRANCH 
Fh Hoss TOGGLE ( 0000 XOR 1 1 1 1 = 1 1 1 1 

( flags: no BRANCH 
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q FORTH Language Dictionary 



TOG BF 



4.8.164 Toggle-BRANCH 
-flag 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



Toggle the state of the BRANCH flag in the MARC4 condition 
code register. 

If the BRANCH flag = 1 THEN reset the BRANCH flag to 0 ELSE 
set the BRANCH flag to 1 . 

Assembler instruction 

18 hex 

EXP ( - ) 

RET ( - ) 

EXP: not affected 

RET: not affected 

CARRY flag not affected 

BRANCH flag = NOT BRANCH flag 

Not affected 

1 

SET BCFCLR BCF 
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q FORTH Language Dictionary 



Example: 



TOG BF 



Error 
3R@ 3 
#D 

I OUT [ E 0 ] 
#LOOP 



( what happens in case of error: 



) 



( show PC, where CPU fails ) 
( suppress compiler warnings ) 



CCRf CCR@ 1010b AND 



( fetch - mask the used flags out 



BC_Flags 
SET_BCF 
CCRf 1010b 
<> IF Error THEN 
CLR_BCF 
CCRf 0000b 
<> IF Error THEN 
CLR_BCF 
TOG_BF 
CCRf 0010b 
<> IF Error THEN 
SET_BCF 
TOG_BF 
CCRf 1000b 
<> IF Error THEN 



flags: C%BI - CARRY % BRANCH x 
BRANCH and CARRY flag is set 
no error occured 

delete BRANCH and CARRY flag 
all flags reset or masked off 
no error occured 

clear table from the compare before 

0000 -> 00B0 

BRANCH flag is set 

no error occured 

define new machine state 

C%B% -> C%0% 

CARRY flag is still set 

no error occured 
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4.8.165 TUCK 



TUCK 



Purpose: 



Duplicates the top of the stack and copies the top of stack 
under the second 4-bit value. 



Category: Stack operation (single-length)/qFORTH macro 

Library Implementation: CODE TUCK SWAP ( n1 n2 -- n2 n1 

OVER ( n2 n1 -- n2 n1 n2 

END-CODE 

EXP ( n1 n2 -- n2 n1 n2 ) 
RET ( - ) 

EXP: 1 element is pushed onto the stack 
RET: not affected 
Not affected 
Not affected 
2 

2TUCK ROT OVER 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 
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TUCK 

Example: 

: TUCK-Example 

12 (--12 ) 

TUCK ( 1 2 -- 2 1 2 ) 

3DR0P ( 2 1 2 -- ) 
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4.8.166 UNTIL 



UNTIL 



Purpose: 



art of the BEGIN ... UNTIL control structure. 

When UNTIL is executed, the BRANCH flag determines the 
result of a conditional branch. 

If the BRANCH flag is set (TRUE), execution will continue 
with the word following the UNTIL statement. If the BRANCH 
flag is FALSE, control branches back to the word following 
BEGIN. 



Category: 



Control structure 



Library Implementation: CODE UNTIL 

TOG_BF 



( complement BRANCH flag 



) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



BRA _$BEGIN 

_$LOOP: 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag not affected 
BRANCH flag = NOT BRANCH flag 
Not affected 
2-3 
BEGIN 



( BRANCH to BEGIN, if TRUE ) 
[EORO] 
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Example: 



UNTIL 



Example 
3 BEGIN 
1 + 
DUP 
7 = UNTIL 



( increment from 3 until 7 
( TOS := TOS + 1 

( DUP current TOS because the compiler will 

( DROP the current value 

( the BRANCH flag is reset after the loop. 
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VARIABLE 



4.8.167 VARIABLE 



Purpose: 



Allocates RAM memory for storage of a 4-bit value. 



The qFORTH syntax is as follows 

VARIABLE <name> [ AT <addr.> ] [ <number> ALLOT ] 

At the time of compilation, VARIABLE adds <name> to the 
dictionary and ALLOTs memory for storage of one normal- 
length value. If AT <addr.> is appended, the variable/s will be 
placed at a specific address (i.e.: 'AT 40h'). 

If <number> ALLOT is appended, a set of <number+1> 4- 
bit memory locations is allocated. At execution time, <name> 
leaves the RAM start address on the Expression Stack. 

The storage ALLOTed by VARIABLE is not initialized. 



Category: 



Predefined data structure 



Stack Effect: 



EXP ( -- d ) at execution time 
RET ( - ) 



Stack Changes: 



EXP: not affected 



RET: not affected 



Flags: 

X Y Registers: 
Bytes Used: 



0 



Not affected 



Not affected 



See Also: 



2VARIABLE ALLOT ARRAY CONSTANT 



4-356 



ill nEL 

^^^^^^^ 
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VARIABLE 

Example: 



3 CONSTANT TimeLen 



VARIABLE RO 27 ALLOT ( return stack: 28 nibbles, used 21 for ) 

( 7 levels of task switching. ) 

( 7 nibbles are free for 1 nibble variables. ) 

VARIABLE SO 1 9 ALLOT ( data stack: 20 nibbles. ) 

VARIABLE MainMode ( one 4-bit variable ) 

2VARIABLE LargeCounter ( one 8-bit variable ) 

VARIABLE Nibble50 AT 50h ( 4-bit at a specific address in RAM ) 

VARIABLE MoreNibbles AT 40h 6 ALLOT 

( 6 nibbles in the RAM. ) 

TimeLen ARRAY ActualTime ( 3 nibble array. ) 
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4.8.168 WHILE 



WHILE 



Purpose: 



Part of the BEGIN ... WHILE ... REPEAT control structure. 
When WHILE is executed, the BRANCH flag determines the 
destination of a conditional branch. 

If the BRANCH flag is set (TRUE), the instructions between 
WHILE and REPEAT are executed. If the BRANCH flag is 
FALSE, control branches to the word just past REPEAT. 



Category: Control structure 

Library Implementation: CODE WHILE 

TOG BF 



( complement BRANCH flag ) 



Stack Effect: 
Stack Changes: 
Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



BRA _$LOOP ( condjump just behind REPEAT 
loop ) 

[EO RO] 
END-CODE 
EXP ( - ) 
RET ( - ) 
EXP: not affected 
RET: not affected 
CARRY flag not affected 
BRANCH flag = NOT BRANCH flag 
Not affected 
1 -3 

BEGIN REPEAT UNTIL 
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Example: 



WHILE 



Example 

10 BEGIN 
1- DUP 
0<> WHILE 
DUP 1 OUT 

REPEAT 



( decrement the TOS , from 1 0 to 0. ) 

( save TOS ) 

( REPEAT decrement while TOS not equal 0 ) 

( after each decrement the TOS contains ) 

( the value of the present index ) 
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Be® 



4.8.169 X fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

72 hex 

EXP ( - - x_h xj ) 
RET ( - ) 

EXP: 2 elements are pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Not affected 

1 

X! 
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x@ 

Example: 



SRAMINIT ( - - ) 

>SP F9h 
SP@ X! 
0 

begin DROP Fh [X]! [X-]@ NOT 

Oh [X]! [X-]@ OR 

TOG_BF ? LEAVE DROP 
X@ 1 - OR ( Test all addresses except 00 & 01 ) 

until ( Attention: RETURN address stack! ) 

Error_Flag ! ( Save result in Error_Flag at FFh ) 

>SP SO ( Reset STACKPOINTER again !! ) 

EON]; ( Don't place in 'ZERO PAGE' ) 
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X! 



4.8.170 X store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

76 hex 

EXP ( x_h xj - - ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Not affected 

1 

X@ Y! Y@ 
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X! 

Example: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 



SRAMINIT ( - - ) 

>SP F9h 
SP@ X! 
0 

begin DROP Fh [X]! [X-]@ NOT 

Oh [X]! [X-]@ OR 

TOG_BF ? LEAVE DROP 
X@ 1 - OR ( Test all addresses except 00 & 01 ) 

until ( Attention: RETURN address stack! ) 

Error_Flag ! ( Save result in Error_Flag at FFh ) 

>SP SO ( Reset STACKPOINTER again !! ) 

EON]; ( Don't place in 'ZERO PAGE' ) 
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[X]@ 



4.8.171 indirect X fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables or 
arrays in the RAM. For the compilation of a qFORTH word which 
uses these MARC4 instructions directly, the qFORTH compiler 
switch $OPTIMIZE-XYTRACE should be turned off (no 
optimizing). 

Assembler instruction 

30 hex 

EXP ( - - n ) 

RET ( - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Used, but not changed 

1 

[X]! [Y]! [Y]@ 
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[X]@ 

Example: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 
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4.8.172 pre increment 
indirect X fetch 



[+X]@ 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access 
variables or arrays in the RAM. For the compilation of a 
qFORTH word which directly uses these MARC4 
instructions, the qFORTH compiler switch 
$OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

31 hex 

EXP ( - - n ) 

RET ( - - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The X register is changed by this instruction 

1 

X! X@ [x]! [X]@ [+X]! [+Y]@ 
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[+X]@ 

Example: 

Purpose: Add the 4-bit number on TOS to an 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 
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[X-]@ 



4.8.173 post-decrement 
indirect X fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

32 hex 

EXP ( - - n ) 

RET ( - - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The X register is changed by this instruction 

1 

X! X@ [X]@ [+X]@ [Y]@ [+Y]@ [Y-]@ 
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[X-]@ 

Example: 

( >Array= Compares two arrays, starting with the last element ) 
( down to lower addresses. Maximal length: 16 elements ) 
( n Addrl Addr2 result is in branch flag ) 



: >Array= 
X! Y! 0 SWAP 
#DO [X-]@ [Y-]@ - OR 
#LOOP 0= 
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[X]! 



4.8.174 indirect X store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

38 hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The X register is not changed by this instruction 

1 

X! X@ [+X]! [X-]! [Y]! [+Y]! [Y-]! 
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[X]! 

Example: 

Purpose: Add the 4-bit number on TOS to an 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 
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4.8.175 



pre increment 
indirect X store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables or 
arrays in the RAM. For the compilation of a qFORTH word which 
directly uses these MARC4 instructions, the qFORTH compiler 
switch $OPTIMIZE-XYTRACE should be turned off (no 
optimizing). 

Assembler instruction 

39 hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The X register is changed by this instruction 

1 

X! X@ [X]! [X-]! [Y]! [+Y]! [Y-]! 
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[+X]! 

Example: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 
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4.8.176 postdecrement 
indirect X store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The X register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

3 A hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The X register is changed by this instruction 

1 

X! X@ [X]@ [+X]@ [Y]! [+Y]! [Y-]! 
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[X-]! 

Example: 

Purpose: Add the 4-bit number on TOS to a 8-bit byte in RAM 

: M+ ( n addr - - ) 

X! [+X]@ + [X-]! 
[X]@ 0+C [X]! 
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XOR 



4.8.177 XOR 



Purpose: 

Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



XOR leaves the bit-wise logical exclusive-or of the top two 
values on the Expression Stack. 

Arithmetic/logical (single-length)/assembler instruction 

04 hex 

EXP ( n1 n2 -- [n1 XOR n2] ) 
RET ( - ) 

EXP: 1 element is popped from the stack. 

RET: not affected 

CARRY flag not affected 

BRANCH flag set, if ([n1 XOR n2] = 0) 

Not affected 

1 

TOGGLE OR AND 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-376 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



Example: 



XORl 



Error 
3R@ 3 
#D0 

I OUT [ E 0 ] 
#LOOP 



( what should happen in case of error: ) 

( show PC, where CPU fails ) 
( suppress compiler warnings. ) 



XOR_Example 



( " ) 



3 5 XOR 
6<> IF 

Error 
THEN 

1100b 1100b XOR 
0000b <> IF 

Error 
THEN 



truth table: a 


b 


a XOR b 


0 


0 


0 


0 


1 


1 


1 


0 


1 


1 


1 


0 


= hexadec: 


3 


5 6 



BRANCH flag is reset [result <> 0] 
XOR top two values; error is not 
activated 

BRANCH flag is set [result = 0] 
XOR top two values; error is not 
activated. 
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4.8.178 Y fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

73 hex 

EXP(--x_hx_l ) 
RET ( - ) 

EXP: 2 elements are pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Not affected 

1 

Y! 
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Y@ 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8-bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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Y! 



4.8.179 Y store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

77 hex 

EXP ( x_h xj - - ) 
RET ( - ) 

EXP: 2 elements are popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Not affected 

1 

Y@ Y! X@ 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-380 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



Y! 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8-bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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[Y]@ 



4.8.180 indirect Y fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables or 
arrays in the RAM. For the compilation of a qFORTH word which 
directly uses these MARC4 instructions, the qFORTH compiler 
switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

34 hex 

EXP ( - - n ) 

RET ( - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

Used, but not changed 

1 

[Y]! [Y]! [Y]@ 
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[Y]@ 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8 bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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4.8.181 pre increment 
indirect Y fetch 



[+Y]@ 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access 
variables or arrays in the RAM. For the compilation of a 
qFORTH word which directly uses these MARC4 
instructions, the qFORTH compiler switch $OPTIMIZE- 
XYTRACE should be turned off (no optimizing). 

Assembler instruction 

35 hex 

EXP ( - - n ) 

RET ( - - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The Y register is changed by this instruction 

1 

Y! Y@ [Y]\ [Y]@ [+Y]! [+Y]@ 
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[+Y]@ 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8-bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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q FORTH Language Dictionary 



[Y-]@ 



4.8.182 postdecrement 
indirect Y fetch 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

36 hex 

EXP ( - - n ) 

RET ( - - ) 

EXP: 1 element is pushed onto the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The Y register is changed by this instruction 

1 

Y! Y@ [Y]@ [+Y]@ [X]@ [+X]@ [X-]@ 



MARC4 4-bit Microcontrollers Programmer's Guide 



4-386 



4747A-4BMCU-01/04 



q FORTH Language Dictionary 



[Y-]@ 

Example: 

( >Array= Compares two arrays, starting with the last element ) 
( down to lower addresses. Maximal length: 16 elements ) 
( n Addrl Addr2 result is in branch flag ) 

: >Array= 
X! Y! 0 SWAP 
#DO [X-]@ [Y-]@ - OR 
#LOOP 0= 
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q FORTH Language Dictionary 



[Y]! 



4.8.183 indirect Y store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

3C hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The Y register is not changed by this instruction 

1 

Y! Y@ [+Y]! [Y-]! [X]! [+X]! [X-]! 
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q FORTH Language Dictionary 



[Y]! 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8 bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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q FORTH Language Dictionary 



4.8.184 pre increment 
indirect Y store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 

X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access variables 
or arrays in the RAM. For the compilation of a qFORTH word 
which directly uses these MARC4 instructions, the qFORTH 
compiler switch $OPTIMIZE-XYTRACE should be turned off 
(no optimizing). 

Assembler instruction 

3D hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The Y register is changed by this instruction 

1 

Y! Y@ [Y]! [Y-]! [X]! [+X]! [X-]! 
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q FORTH Language Dictionary 



[+Y]! 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8 bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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q FORTH Language Dictionary 



4.8.185 postdecrement 
indirect Y store 



Purpose: 



Category: 
MARC4 Opcode: 
Stack Effect: 

Stack Changes: 

Flags: 



X Y Registers: 
Bytes Used: 
See Also: 



The Y register can be used as a pointer to access 
variables or arrays in the RAM. For the compilation of a 
qFORTH word which directly uses these MARC4 
instructions, the qFORTH compiler switch $OPTIMIZE- 
XYTRACE should be turned off (no optimizing). 

Assembler instruction 

3E hex 

EXP ( n - - ) 

RET ( - - ) 

EXP: 1 element is popped from the stack 

RET: not affected 

CARRY flag not affected 

BRANCH flag not affected 

The Y register is changed by this instructions 

1 

Y! Y@ [Y]@ [+Y]@ [Y]! [+X]! [X-]! 
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q FORTH Language Dictionary 



[Y-]! 

Example 1 : 

4 ARRAY Ramaddr AT 30h 



$OPTIMIZE - XYTRACE, -XY@! 



: Y-STORE 

Ramaddr [3] Y! ( assign the variable Ramaddr to the Y register 

5 [Y-]! ( store 5 in the RAM location 33 

6 [Y-]! ( store 6 in the RAM location 32 
2 [Y-]! ( store 2 in the RAM location 31 

7 [+Y]! ( store 7 in the RAM location 31 



$OPTIMIZE +XY@!, + XYTRACE 
Example 2: 

Purpose: Substract a 4-bit number on TOS from 8 bits in RAM 



M-! 

Y! [+Y]@ -[Y-]! [Y]@ 0-c [Y]! 



( n addr - - ) 
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q FORTH Language Dictionary 
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Index of "Detailed Description of the qFORTH Language" 



Symbols 

! 4-24 
- 4-46 
#DO 4-28 
#LOOP 4-30 
$AUTOSLEEP 4-32 
$INCLUDE 4-170 
SRAMSIZE 4-172 
SRESET 4-34 
SROMSIZE 4-172 
( comment) 4-36 
+ 4-38 
+! 4-40 
+C 4-42 
+LOOP 4-44 
4-118 
4-120 
4-122 
< 4-124 
<= 4-126 
<> 4-128 
<ROT 4-130 
= 4-132 
> 4-134 
>= 4-136 
>R 4-138 
>RP FCh 4-320 
>SP 4-330 
?DO 4-140 
?DUP 4-142 
-7LEAVE 4-48 
7LEAVE 4-144 
@ 4-146 
[+X]! 4-372 
[+X]@ 4-366 
[+Y]! 4-390 
[+Y]@ 4-384 
[X-]! 4-374 
[X]! 4-370 
[X-]@ 4-368 
[X]@ 4-364 
[Y-]! 4-392 
[Y]! 4-388 
[Y-]@ 4-386 
[Y]@ 4-382 
' 4-26 

'INTO ... INT7' 4-260 
'SWI0 ... SWI7' 4-336 

Numerics 

0... Fh(15) 4-52 



0<> 

0= 

1- 

1-! 

1 + 

1+! 

2! 

2* 

2/ 



4-54 
4-56 

4-62 
4-64 
4-58 
4-60 

4-66 

4-68 

4-70 



2<ROT 4-72 
2>R 4-74 
2@ 4-76 
2ARRAY 4-78 
2CONSTANT 4-80 
2DROP 4-82 
2DUP 4-84 
2 LA R RAY 4-86 
2NIP 4-88 
20VER 4-90 
2R> 4-92 
2R@ 4-94 
2ROT 4-96 
2SWAP 4-98 
2TUCK 4-100 
2VARIABLE 4-102 
3! 4-104 
3>R 4-106 
3@ 4-108 
3DROP 4-110 
3DUP 4-112 
3R> 4-114 
3R@ 4-116 

A 

ADD 4-38 
ADDC 4-42 
AGAIN 4-148 
ALLOT 4-150 
AND 4-152 
ARRAY 4-154 
AT 4-156 



B 

BEGIN 



4-158 



c 

-C 4-50 
CASE 4-160 
CCR! 4-162 
CCR@ 4-164 
CLRBCF 4-166 
CMP_EQ 4-132 
CMP_GE 4-136 
CMP_GT 4-134 
CMPJ.E 4-126 
CMPJ.T 4-124 
CMP_NE 4-128 
CODE 4-168 
CONSTANT 4-174 



D 

D- 

D-! 

D+ 

D+! 

D< 

D<= 



4-180 
4-182 
4-176 
4-178 
4-192 
4-194 
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Do 4-196 
D= 4-198 
D> 4-200 
D>= 4-202 
D>S 4-204 
DOo 4-184 
D0= 4-186 
D2* 4-188 
D2/ 4-190 
DAA 4-206 
DAS 4-208 
DEC 4-62 
DECR 4-210 
DEPTH 4-212 
Dl 4-214 
DMAX 4-216 
DMIN 4-218 
DNEGATE 4-220 
DO 4-222 
DROP 4-224 
DROPR 4-226 
DTABLE® 4-228 
DTOGGLE 4-230 
DUP 4-232 

E 

El 4-234 
ELSE 4-236 
ENDCASE 4-240 
END-CODE 4-238 
ENDOF 4-242 
ERASE 4-244 
EXECUTE 4-248 
EXIT 4-120, 4-246 

F 

FILL 4-250 
I 

I 4-252 
IF 4-254 
IN 4-256 
INC 4-58 
INDEX 4-258 

J 

J 4-262 



LARRAY 4-264 
LIT_0 ... LIT_F 4-52 
LOOP 4-266 

M 

M- 4-270 
M+ 4-268 
MAX 4-272 
MIN 4-274 
MOVE 4-276 
MOVE> 4-278 



N 

NEGATE 4-280 
NIP 4-204 
NOP 4-282 
NOT 4-284 

o 

OF 4-286 
OR 4-288 
OUT 4-290 
OVER 4-292 



P 

PICK 



4-294 



R 

R> 4-296 

R@ 4-252 

R0 4-320 

RDEPTH 4-298 

REPEAT 4-300 

RFREE 4-302 

ROL 4-304 

ROLL 4-306 

ROMByteOTABLE 4-308 

ROMCONST 4-310 

ROR 4-312 

ROT 4-314 

RP! 4-318 

RP@ 4-316 

RTI 4-120 

s 

S>D 4-322 
SO 4-330 
SET_BCF 4-332 
SHL 4-68 
SHR 4-70 
SLEEP 4-326 
SP! 4-328 
SP@ 4-324 
SUB 4-46 
SUBB 4-50 
SWAP 4-334 

T 

T-! 4-340 
T+! 4-338 
TD-! 4-344 
TD+! 4-342 
THEN 4-346 
TOG_BF 4-350 
TOGGLE 4-348 
TUCK 4-352 



u 

UNTIL 



4-354 



I-2 
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V 

VARIABLE 4-356 



w 

WHILE 4-358 



X 

X! 4-362 
X@ 4-360 
XOR 4-376 

Y 

Y! 4-380 
Y@ 4-378 
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